open_api_spex v2.3.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
Adds schemas to the api spec from the modules specified in the Operations
Declares a struct based OpenApiSpex.Schema
Validate params against OpenApiSpex.Schema
Validate all params in Plug.Conn
against OpenApiSpex.Operation
parameter
and requestBody
schemas
Link to this section Functions
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.
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.
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
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.
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.