Specs

add_schemas(OpenApiSpex.OpenApi.t(), [module()]) :: OpenApiSpex.OpenApi.t()

Add more schemas to an existing OpenApi struct.

This is useful when the schemas are not used by a Plug or Controller. Perhaps they're used by a Phoenix Channel.

Example

defmodule MyAppWeb.ApiSpec do
  def spec do
    %OpenApiSpex.OpenApi{
      # ...
      paths: OpenApiSpex.Paths.from_router(MyAppWeb.Router)
      # ...
    }
    |> OpenApiSpex.resolve_schema_modules()
    |> OpenApiSpex.add_schemas([
      MyAppWeb.Schemas.Message,
      MyAppWeb.Schemas.Channel
    ])
  end
end

Build a Schema struct from the given keyword list.

This function adds functionality over defining a schema with struct literal sytax using %OpenApiSpex.Struct{}:

• When the :module option is given, the :"x-struct and :title attributes of the schema will be autopopulated based on the given module
• Validations are performed on the schema to ensure it is correct.

Options

• :module (module) - A module in the application that the schema should be associated with.

Specs

cast(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(),
  any()
) :: {:ok, any()} | {:error, String.t()}

Cast params to conform to a OpenApiSpex.Schema.

See OpenApiSpex.Schema.cast/3 for additional examples and details.

Specs

cast(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Operation.t(),
  Plug.Conn.t(),
  content_type | nil
) :: {:ok, Plug.Conn.t()} | {:error, String.t()}
when content_type: String.t()

Cast all params in Plug.Conn to conform to the schemas for OpenApiSpex.Operation.

Returns {:ok, Plug.Conn.t} with params and body_params fields updated if successful, or {:error, reason} if casting fails.

content_type may optionally be supplied to select the requestBody schema.

Cast and validate a value against a given Schema.

Cast and validate a value against a given Schema belonging to a given OpenApi spec.

Specs

error!(atom(), OpenApiSpex.Schema.t(), keyword()) :: no_return()

Raises compile time errors for improperly defined schemas.

Specs

resolve_schema(
  OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(),
  OpenApiSpex.Components.schemas_map()
) :: OpenApiSpex.Schema.t()

Resolve a schema or reference to a schema.

Specs

resolve_schema_modules(OpenApiSpex.OpenApi.t()) :: OpenApiSpex.OpenApi.t()

Adds schemas to the api spec from the modules specified in the Operations.

Eg, if the response schema for an operation is defined with:

responses: %{
  200 => Operation.response("User", "application/json", UserResponse)
}

Then the UserResponse.schema() function will be called to load the schema, and a Reference to the loaded schema will be used in the operation response.

See OpenApiSpex.schema macro for a convenient syntax for defining schema modules.

Declares a struct based OpenApiSpex.Schema

• defines the schema/0 callback
• ensures the schema is linked to the module by "x-struct" extension property
• defines a struct with keys matching the schema properties
• defines a @type t for the struct
• derives a Jason.Encoder and/or Poison.Encoder for the struct

See OpenApiSpex.Schema for additional examples and details.

Example

require OpenApiSpex

defmodule User do
  OpenApiSpex.schema %{
    title: "User",
    description: "A user of the app",
    type: :object,
    properties: %{
      id: %Schema{type: :integer, description: "User ID"},
      name:  %Schema{type: :string, description: "User name", pattern: ~r/[a-zA-Z][a-zA-Z0-9_]+/},
      email: %Schema{type: :string, description: "Email address", format: :email},
      inserted_at: %Schema{type: :string, description: "Creation timestamp", format: :'date-time'},
      updated_at: %Schema{type: :string, description: "Update timestamp", format: :'date-time'}
    },
    required: [:name, :email],
    example: %{
      "id" => 123,
      "name" => "Joe User",
      "email" => "joe@gmail.com",
      "inserted_at" => "2017-09-12T12:34:55Z",
      "updated_at" => "2017-09-13T10:11:12Z"
    }
  }
end

Example

This example shows the :struct? and :derive? options that may be passed to schema/2:

defmodule MyAppWeb.Schemas.User do
  require OpenApiSpex
  alias OpenApiSpex.Schema

  OpenApiSpex.schema(
    %{
      type: :object,
      properties: %{
        name: %Schema{type: :string}
      }
    },
    struct?: false,
    derive?: false
  )
end

Options

• :struct? (boolean) - When false, prevents the automatic generation of a struct definition for the schema module.
• :derive? (boolean) When false, prevents the automatic generation of a @derive call for either Poison.Encoder or Jason.Encoder. Using this option can prevent "... protocol has already been consolidated ..." compiler warnings.

Creates an %OpenApi{} struct from a map.

This is useful when importing existing JSON or YAML encoded schemas.

Example

# Importing an existing JSON encoded schema
open_api_spec_from_json = "encoded_schema.json"
  |> File.read!()
  |> Jason.decode!()
  |> OpenApiSpex.OpenApi.Decode.decode()

# Importing an existing YAML encoded schema
open_api_spec_from_yaml = "encoded_schema.yaml"
  |> YamlElixir.read_all_from_file!()
  |> OpenApiSpex.OpenApi.Decode.decode()

Specs

validate(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(),
  any()
) :: :ok | {:error, String.t()}

Validate params against OpenApiSpex.Schema.

See OpenApiSpex.Schema.validate/3 for examples of error messages.

Specs

validate(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Operation.t(),
  Plug.Conn.t(),
  content_type | nil
) :: :ok | {:error, String.t()}
when content_type: String.t()

Validate all params in Plug.Conn against OpenApiSpex.Operation parameter and requestBody schemas.

content_type may be optionally supplied to select the requestBody schema.

Validate the compiled schema's properties to ensure the schema is not improperly defined. Only errors which would cause a given schema to always fail should be raised here.

Used for validating the schema at compile time, otherwise we're forced to raise errors for improperly defined schemas at runtime.