open_api_spex v2.2.0 OpenApiSpex View Source

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

Link to this section Summary

Functions

Cast params to conform to a OpenApiSpex.Schema

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

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

Declares a struct based OpenApiSpex.Schema

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

Link to this section Functions

Link to this function cast(spec, schema, params) View Source
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
cast(
  OpenApiSpex.OpenApi.t(),
  OpenApiSpex.Operation.t(),
  Plug.Conn.t(),
  content_type | nil
) :: {:ok, any()} | {:error, String.t()}
when content_type: String.t()

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

content_type may optionally be supplied to select the requestBody schema.

Link to this function resolve_schema_modules(spec) View Source
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 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
Link to this function validate(spec, schema, params) View Source
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
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.