View Source OpenApiSpex (open_api_spex v3.18.3)
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.
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 Types
Link to this section Functions
@spec add_parameter_content_parser( OpenApiSpex.OpenApi.t(), content_type | [content_type], parser :: module() ) :: OpenApiSpex.OpenApi.t() when content_type: String.t() | Regex.t()
@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.
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.
@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.
@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.
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()}
Cast and validate a value against a given Schema.
Cast and validate a value against a given Schema belonging to a given OpenApi spec.
@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.
@spec resolve_schema( OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | module(), OpenApiSpex.Components.schemas_map() ) :: OpenApiSpex.Schema.t() | nil
Resolve a schema or reference to a schema.
@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.
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/orPoison.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 eitherPoison.Encoder
orJason.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()
@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.
@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.
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.