View Source OpenApiSpex (open_api_spex v3.16.0)

Provides the entry-points for defining schemas, validating and casting.

Link to this section Summary

Functions

Add more schemas to an existing OpenApi struct.

Get casted body params from a Plug.Conn. If the conn has not been yet casted nil is returned.

Build a Schema struct from the given keyword list.

Cast params to conform to a OpenApiSpex.Schema.

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

Cast and validate a value against a given Schema.

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

Raises compile time errors for improperly defined schemas.

Get casted params from a Plug.Conn. If the conn has not been yet casted nil is returned.

Resolve a schema or reference to a schema.

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

Creates an %OpenApi{} struct from a map.

Validate params against OpenApiSpex.Schema.

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

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.

Link to this section Types

@type cast_opt() :: {:replace_params, boolean()} | {:apply_defaults, boolean()}

Link to this section Functions

Link to this function

add_parameter_content_parser(spec, content_type, parser)

View Source
@spec add_parameter_content_parser(
  OpenApiSpex.OpenApi.t(),
  content_type | [content_type],
  parser :: module()
) :: OpenApiSpex.OpenApi.t()
when content_type: String.t() | Regex.t()
Link to this function

add_schemas(spec, schema_modules)

View Source
@spec 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

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
@spec body_params(Plug.Conn.t()) :: nil | map()

Get casted body params from a Plug.Conn. If the conn has not been yet casted nil is returned.

Link to this function

build_schema(body, opts \\ [])

View Source

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

Options

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

cast(spec, schema, params)

View Source
This function is deprecated. Use OpenApiSpex.cast_value/3 or cast_value/2 instead.
@spec 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.

Link to this function

cast(spec, operation, conn, content_type \\ nil)

View Source
This function is deprecated. Use OpenApiSpex.cast_and_validate/3 instead.
@spec 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.

Link to this function

cast_and_validate(spec, operation, conn, content_type \\ nil, opts \\ [])

View Source
@spec cast_and_validate(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Operation.t(),
  Plug.Conn.t(),
  content_type :: nil | String.t(),
  opts :: [cast_opt()]
) :: {:error, [OpenApiSpex.Cast.Error.t()]} | {:ok, Plug.Conn.t()}
Link to this function

cast_value(value, schema)

View Source

Cast and validate a value against a given Schema.

Link to this function

cast_value(value, schema, spec)

View Source

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

Link to this function

error!(error, schema, details \\ [])

View Source
@spec error!(atom(), OpenApiSpex.Schema.t(), keyword()) :: no_return()

Raises compile time errors for improperly defined schemas.

@spec params(Plug.Conn.t()) :: nil | map()

Get casted params from a Plug.Conn. If the conn has not been yet casted nil is returned.

Link to this function

resolve_schema(schema, schemas)

View Source

Resolve a schema or reference to a schema.

Link to this function

resolve_schema_modules(spec)

View Source
@spec 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.

Link to this macro

schema(body, opts \\ [])

View Source (macro)

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

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-1

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

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

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()
Link to this function

title_from_module(module)

View Source
Link to this function

validate(spec, schema, params)

View Source
This function is deprecated. Use OpenApiSpex.cast_value/3 or cast_value/2 instead.
@spec 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.

Link to this function

validate(spec, operation, conn, content_type \\ nil)

View Source
This function is deprecated. Use OpenApiSpex.cast_and_validate/4 instead.
@spec 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.

Link to this function

validate_compiled_schema(schema)

View Source

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.

Link to this function

validate_compiled_schema(arg, schema)

View Source

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