open_api_spex v1.0.0 OpenApiSpex.Schema behaviour View Source
Defines the OpenApiSpex.Schema.t
type and operations for casting and validating against a schema.
Link to this section Summary
Functions
Cast a simple value to the elixir type defined by a schema
Validate a value against a Schema
Callbacks
A module implementing the OpenApiSpex.Schema
behaviour should export a schema/0
function
that produces an OpenApiSpex.Schema
struct
Link to this section Types
t() :: %OpenApiSpex.Schema{description: String.t, maximum: number | nil, required: [String.t] | nil, properties: %{optional(atom) => OpenApiSpex.Schema.t | OpenApiSpex.Reference.t} | nil, multipleOf: number | nil, readOnly: boolean | nil, minItems: integer | nil, externalDocs: OpenApiSpex.ExternalDocumentation.t | nil, uniqueItems: boolean | nil, not: OpenApiSpex.Schema.t | OpenApiSpex.Reference.t | nil, maxItems: integer | nil, nullable: boolean | nil, oneOf: [OpenApiSpex.Schema.t | OpenApiSpex.Reference.t] | nil, minLength: integer | nil, format: String.t | nil, discriminator: OpenApiSpex.Discriminator.t | nil, pattern: String.t | Regex.t | nil, minProperties: integer | nil, title: String.t, maxLength: integer | nil, maxProperties: integer | nil, items: OpenApiSpex.Schema.t | OpenApiSpex.Reference.t | nil, exclusiveMinimum: boolean | nil, example: any, exclusiveMaximum: boolean | nil, anyOf: [OpenApiSpex.Schema.t | OpenApiSpex.Reference.t] | nil, minimum: number | nil, writeOnly: boolean | nil, xml: OpenApiSpex.Xml.t | nil, additionalProperties: boolean | OpenApiSpex.Schema.t | OpenApiSpex.Reference.t | nil, default: any | nil, deprecated: boolean | nil, allOf: [OpenApiSpex.Schema.t | OpenApiSpex.Reference.t] | nil, enum: [String.t] | nil, type: atom, "x-struct": module | nil}
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.
Example
alias OpenApiSpex.Schema
%Schema{
title: "User",
type: :object,
properties: %{
id: %Schema{type: :integer, minimum: 1},
name: %Schema{type: :string, pattern: "[a-zA-Z][a-zA-Z0-9_]+"},
email: %Scheam{type: :string, format: :email},
last_login: %Schema{type: :string, format: :"date-time"}
},
required: [:name, :email],
example: %{
"name" => "joe",
"email" => "joe@gmail.com"
}
}
Link to this section Functions
cast(OpenApiSpex.Schema.t | OpenApiSpex.Reference.t, any, %{optional(String.t) => OpenApiSpex.Schema.t | OpenApiSpex.Reference.t}) :: {:ok, any} | {:error, String.t}
Cast a simple value to the elixir type defined by a schema.
By default, object types are cast to maps, however if the “x-struct” attribute is set in the schema, the result will be constructed as an instance of the given struct type.
Examples
iex> OpenApiSpex.Schema.cast(%Schema{type: :integer}, "123", %{})
{:ok, 123}
iex> {:ok, dt = %DateTime{}} = OpenApiSpex.Schema.cast(%Schema{type: :string, format: :"date-time"}, "2018-04-02T13:44:55Z", %{})
...> dt |> DateTime.to_iso8601()
"2018-04-02T13:44:55Z"
validate(OpenApiSpex.Schema.t | OpenApiSpex.Reference.t, any, %{optional(String.t) => OpenApiSpex.Schema.t | OpenApiSpex.Reference.t}) :: :ok | {:error, String.t}
Validate a value against a Schema.
This expects that the value has already been cast
to the appropriate data type.
Examples
iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :integer, minimum: 5}, 3, %{})
{:error, "3 is smaller than minimum 5"}
iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.*)@(.*)"}, "joe@gmail.com", %{})
:ok
iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.*)@(.*)"}, "joegmail.com", %{})
{:error, "Value does not match pattern: (.*)@(.*)"}
Link to this section Callbacks
A module implementing the OpenApiSpex.Schema
behaviour should export a schema/0
function
that produces an OpenApiSpex.Schema
struct.