open_api_spex

v3.4.0

open_api_spex v3.4.0 OpenApiSpex View Source

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

Link to this section Summary

Functions

cast(spec, schema, params)

Cast params to conform to a OpenApiSpex.Schema

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

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

cast_and_validate(spec, operation, conn, content_type \\ nil)
error!(error, schema, details \\ [])

Raises compile time errors for improperly defined schemas

path_to_string(error)
resolve_schema_modules(spec)

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

schema(body)

Declares a struct based OpenApiSpex.Schema

validate(spec, schema, params)

Validate params against OpenApiSpex.Schema

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

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

validate_compiled_schema(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

validate_compiled_schema(arg, schema)

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 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, 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) View Source

Link to this function

error!(error, schema, details \\ []) View Source 
error!(atom(), OpenApiSpex.Schema.t(), keyword()) :: no_return()

Raises compile time errors for improperly defined schemas.

Link to this function

path_to_string(error) View Source

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.

Link to this macro

schema(body) 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 

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.

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.