phoenix_swagger v0.6.2 PhoenixSwagger.Schema
Struct and helpers for swagger schema.
Fields should reflect the swagger SchemaObject specification http://swagger.io/specification/#schemaObject
Summary
Functions
Boolean indicating that additional properties are allowed, or
a schema to be used for validating any additional properties not listed in properties
.
Default behaviour is to allow additional properties
Used to combine multiple schemas, requiring a value to conform to all schemas.
Can be used in conjunction with discriminator
to define polymorphic inheritance relationships.
See http://swagger.io/specification/#composition-and-inheritance—polymorphism—83
Construct an array schema, where the array items schema is a ref to the given name
Sets the default value for the schema. The value provided should validate against the schema sucessfully
Sets the description for the schema
Specifies the name of a property that identifies the polymorphic schema for a JSON object.
The value of this property should be the name of this schema, or another schema that inherits
from this schema using all_of
.
See http://swagger.io/specification/#composition-and-inheritance—polymorphism—83
Restricts the schema to a fixed set of values
Adds an example of the schema
Boolean indicating that value for maximum
is excluded from the valid range.
When true: x < maximum
, when false: x <= maximum
Boolean indicating that value for minimum
is excluded from the valid range.
When true: x > minimum
, when false: x => minimum
Sets the format of a Schema with type: :string
Sets the schema/s for the items of an array.
Use a single schema for arrays when each item should have the same schema.
Use a list of schemas when the array represents a tuple, each element will be validated against
the corresponding schema in the items
list
Restricts the maximimum number of items in an array
schema
Constrains the maximum length of a string to the given value
Limits the maximum number of properties an object
schema may contain
Specifies a maximum numeric value for :integer or :number types
Restricts the minimum number of items in an array
schema
Constrains the minimum length of a string to the given value
Limits the minimum number of properties an object
schema may contain
Specifies a minimum numeric value for :integer or :number types
Limits a values of numeric type (:integer or :number) to multiples of the given amount
Restricts a string schema to match a regular expression, given as a string
Sets a property of the Schema
Construct a schema reference, using name of definition in this swagger document, or a complete path
Makes one or more properties required in an object schema
Sets the title of the schema
Sets the type of for the schema.
Valid values are :string
, :integer
, :number
, :object
, :array
, :boolean
, :null
,
or a list of those basic types
Boolean that when true, requires each item of an array
schema to be unique
Macros
Construct a new %Schema{} struct using the schema DSL
Defines multiple properties for a schema with a custom DSL syntax
Functions
Boolean indicating that additional properties are allowed, or
a schema to be used for validating any additional properties not listed in properties
.
Default behaviour is to allow additional properties.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.property(:name, :string, "Full name", maxLength: 255)
...> |> Schema.additional_properties(false)
%PhoenixSwagger.Schema{
type: :object,
properties: %{
name: %PhoenixSwagger.Schema{
type: :string,
description: "Full name",
maxLength: 255
}
},
additionalProperties: false
}
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.property(:name, :string, "Full name", maxLength: 255)
...> |> Schema.additional_properties(%Schema{type: :number})
%PhoenixSwagger.Schema{
type: :object,
properties: %{
name: %PhoenixSwagger.Schema{
type: :string,
description: "Full name",
maxLength: 255
}
},
additionalProperties: %PhoenixSwagger.Schema{
type: :number
}
}
Used to combine multiple schemas, requiring a value to conform to all schemas.
Can be used in conjunction with discriminator
to define polymorphic inheritance relationships.
See http://swagger.io/specification/#composition-and-inheritance—polymorphism—83
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{}
...> |> Schema.all_of([Schema.ref("#definitions/Contact"), Schema.ref("#definitions/CreditHistory")])
%PhoenixSwagger.Schema{
allOf: [
%PhoenixSwagger.Schema{'$ref': "#definitions/Contact"},
%PhoenixSwagger.Schema{'$ref': "#definitions/CreditHistory"},
]
}
Construct an array schema, where the array items schema is a ref to the given name.
Example
iex> PhoenixSwagger.Schema.array(:User)
%PhoenixSwagger.Schema{
items: %PhoenixSwagger.Schema{"$ref": "#/definitions/User"},
type: :array
}
iex> PhoenixSwagger.Schema.array(:string)
%PhoenixSwagger.Schema{
items: %PhoenixSwagger.Schema{type: :string},
type: :array
}
Sets the default value for the schema. The value provided should validate against the schema sucessfully.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string, format: :datetime}
...> |> Schema.default("2017-01-01T00:00:00Z")
%PhoenixSwagger.Schema{
type: :string,
format: :datetime,
default: "2017-01-01T00:00:00Z"
}
Sets the description for the schema.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.description("A user")
%PhoenixSwagger.Schema{description: "A user"}
Specifies the name of a property that identifies the polymorphic schema for a JSON object.
The value of this property should be the name of this schema, or another schema that inherits
from this schema using all_of
.
See http://swagger.io/specification/#composition-and-inheritance—polymorphism—83
## Example
iex> alias PhoenixSwagger.Schema …> %Schema{} …> |> Schema.type(:object) …> |> Schema.title(“Pet”) …> |> Schema.property(:pet_type, :string, “polymorphic pet schema type”, example: “Dog”) …> |> Schema.discriminator(:pet_type) %Schema{
type: :object,
title: "Pet",
properties: %{
pet_type: %Schema{
type: :string,
description: "polymorphic pet schema type",
example: "Dog"
}
},
discriminator: :pet_type,
required: [:pet_type]
}
Restricts the schema to a fixed set of values.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string}
...> |> Schema.enum(["red", "yellow", "green"])
%PhoenixSwagger.Schema{type: :string, enum: ["red", "yellow", "green"]}
Adds an example of the schema.
## Example
iex> alias PhoenixSwagger.Schema …> %Schema{type: :object, properties: %{phone_number: %Schema{type: :string}}} …> |> Schema.example(%{phone_number: “555-123-456”}) %PhoenixSwagger.Schema{
type: :object,
properties: %{
phone_number: %PhoenixSwagger.Schema{
type: :string
}
},
example: %{phone_number: "555-123-456"}
}
Boolean indicating that value for maximum
is excluded from the valid range.
When true: x < maximum
, when false: x <= maximum
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :number}
...> |> Schema.maximum(128)
...> |> Schema.exclusive_maximum(true)
%PhoenixSwagger.Schema{
type: :number,
maximum: 128,
exclusiveMaximum: true
}
Boolean indicating that value for minimum
is excluded from the valid range.
When true: x > minimum
, when false: x => minimum
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :number}
...> |> Schema.minimum(16)
...> |> Schema.exclusive_minimum(true)
%PhoenixSwagger.Schema{
type: :number,
minimum: 16,
exclusiveMinimum: true
}
Sets the format of a Schema with type: :string
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string} |> Schema.format(:datetime)
%PhoenixSwagger.Schema{type: :string, format: :datetime}
Sets the schema/s for the items of an array.
Use a single schema for arrays when each item should have the same schema.
Use a list of schemas when the array represents a tuple, each element will be validated against
the corresponding schema in the items
list.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :array}
...> |> Schema.items(%Schema{type: :string})
%PhoenixSwagger.Schema{type: :array, items: %PhoenixSwagger.Schema{type: :string}}
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :array}
...> |> Schema.items([%Schema{type: :string}, %Schema{type: :number}])
%PhoenixSwagger.Schema{
type: :array,
items: [%PhoenixSwagger.Schema{type: :string}, %PhoenixSwagger.Schema{type: :number}]
}
Restricts the maximimum number of items in an array
schema.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :array}
...> |> Schema.max_items(25)
%PhoenixSwagger.Schema{type: :array, maxItems: 25}
Constrains the maximum length of a string to the given value.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string}
...> |> Schema.max_length(255)
%PhoenixSwagger.Schema{type: :string, maxLength: 255}
Limits the maximum number of properties an object
schema may contain.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.max_properties(10)
%PhoenixSwagger.Schema{type: :object, maxProperties: 10}
Specifies a maximum numeric value for :integer or :number types.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :integer}
...> |> Schema.maximum(100)
%PhoenixSwagger.Schema{type: :integer, maximum: 100}
Restricts the minimum number of items in an array
schema.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :array}
...> |> Schema.min_items(1)
%PhoenixSwagger.Schema{type: :array, minItems: 1}
Constrains the minimum length of a string to the given value.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string}
...> |> Schema.min_length(32)
%PhoenixSwagger.Schema{type: :string, minLength: 32}
Limits the minimum number of properties an object
schema may contain.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.min_properties(1)
%PhoenixSwagger.Schema{type: :object, minProperties: 1}
Specifies a minimum numeric value for :integer or :number types.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :integer}
...> |> Schema.minimum(10)
%PhoenixSwagger.Schema{type: :integer, minimum: 10}
Limits a values of numeric type (:integer or :number) to multiples of the given amount.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :number}
...> |> Schema.multiple_of(7)
%PhoenixSwagger.Schema{type: :number, multipleOf: 7}
Restricts a string schema to match a regular expression, given as a string.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :string}
...> |> Schema.pattern(~S"^(([0-9]{2}))?[0-9]{4}-[0-9]{4}$")
%PhoenixSwagger.Schema{type: :string, pattern: ~S"^(([0-9]{2}))?[0-9]{4}-[0-9]{4}$"}
Sets a property of the Schema.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.property(:name, :string, "Full name", required: true, maxLength: 256)
...> |> Schema.property(:address, [:string, "null"], "Street Address")
...> |> Schema.property(:friends, Schema.array(:User), "Friends list", required: true)
%PhoenixSwagger.Schema{
type: :object,
properties: %{
friends: %PhoenixSwagger.Schema{
type: :array,
description: "Friends list",
items: %PhoenixSwagger.Schema{"$ref": "#/definitions/User"}
},
address: %PhoenixSwagger.Schema{
type: [:string, "null"],
description: "Street Address"
},
name: %PhoenixSwagger.Schema{
type: :string,
description: "Full name",
maxLength: 256
}
},
required: [:friends, :name]
}
Construct a schema reference, using name of definition in this swagger document, or a complete path.
Example
iex> PhoenixSwagger.Schema.ref(:User)
%PhoenixSwagger.Schema{"$ref": "#/definitions/User"}
iex> PhoenixSwagger.Schema.ref("../common/Error.json")
%PhoenixSwagger.Schema{"$ref": "../common/Error.json"}
Makes one or more properties required in an object schema.
## Example
iex> alias PhoenixSwagger.Schema …> %Schema{type: :object, properties: %{phone_number: %Schema{type: :string}}} …> |> Schema.required(:phone_number) %PhoenixSwagger.Schema{
type: :object,
properties: %{
phone_number: %PhoenixSwagger.Schema{
type: :string
}
},
required: [:phone_number]
}
iex> alias PhoenixSwagger.Schema …> %Schema{type: :object, properties: %{phone_number: %Schema{type: :string}, address: %Schema{type: :string}}} …> |> Schema.required([:phone_number, :address]) %PhoenixSwagger.Schema{
type: :object,
properties: %{
phone_number: %PhoenixSwagger.Schema{
type: :string
},
address: %PhoenixSwagger.Schema{
type: :string
}
},
required: [:phone_number, :address]
}
Sets the title of the schema
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.title("User")
%PhoenixSwagger.Schema{title: "User"}
Sets the type of for the schema.
Valid values are :string
, :integer
, :number
, :object
, :array
, :boolean
, :null
,
or a list of those basic types.
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{}
...> |> Schema.type(:string)
%PhoenixSwagger.Schema{type: :string}
iex> alias PhoenixSwagger.Schema
...> %Schema{}
...> |> Schema.type([:string, :integer])
%PhoenixSwagger.Schema{type: [:string, :integer]}
Macros
Construct a new %Schema{} struct using the schema DSL.
This macro is similar to PhoenixSwagger.swagger_schema, except that it produces a Schema struct instead of a plain map with string keys.
Example
iex> require PhoenixSwagger.Schema, as: Schema
...> Schema.new do
...> type :object
...> properties do
...> name :string, "user name", required: true
...> date_of_birth :string, "date of birth", format: :datetime
...> end
...> end
%Schema{
type: :object,
properties: %{
name: %Schema {
type: :string,
description: "user name"
},
date_of_birth: %Schema {
type: :string,
format: :datetime,
description: "date of birth"
}
},
required: [:name]
}
Defines multiple properties for a schema with a custom DSL syntax
Example
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object}
...> |> Schema.properties do
...> name :string, "Full Name", required: true
...> dateOfBirth :string, "Date of birth", format: :datetime
...> end
%PhoenixSwagger.Schema{
type: :object,
properties: %{
name: %PhoenixSwagger.Schema{
type: :string,
description: "Full Name",
},
dateOfBirth: %PhoenixSwagger.Schema{
type: :string,
description: "Date of birth",
format: :datetime
}
},
required: [:name]
}