open_api_spex v3.5.1 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

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

Resolve a schema or reference to a schema

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

Declares a struct based OpenApiSpex.Schema

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 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()}

This function is deprecated. Use OpenApiSpex.cast_value/3 or cast_value/2 instead.

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

This function is deprecated. Use OpenApiSpex.cast_and_validate/3 instead.

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

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

Raises compile time errors for improperly defined schemas.

Resolve a schema or reference to a 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 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

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()
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()}

This function is deprecated. Use OpenApiSpex.cast_value/3 or cast_value/2 instead.

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

This function is deprecated. Use OpenApiSpex.cast_and_validate/4 instead.

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.