phoenix_swagger v0.7.0 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

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

additional_properties(model, bool_or_schema)

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
  }
}
all_of(model, schemas)

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"},
  ]
}
array(name)

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
}
default(model, default)

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"
}
description(model, desc)

Sets the description for the schema.

Example

iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.description("A user")
%PhoenixSwagger.Schema{description: "A user"}
discriminator(model, property_name)

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]

}

enum(model, values)

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"]}
example(model, example)

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"}

}

exclusive_maximum(model, exclusive?)

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
}
exclusive_minimum(model, exclusive?)

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
}
format(model, format)

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}
items(model, item_schema)

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}]
}
max_items(model, value)

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}
max_length(model, value)

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}
max_properties(model, value)

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}
maximum(model, maximum)

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}
min_items(model, value)

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}
min_length(model, value)

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}
min_properties(model, value)

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}
minimum(model, minimum)

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}
multiple_of(model, number)

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}
pattern(model, regex_pattern)

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}$"}
property(model, name, type_or_schema, description \\ nil, opts \\ [])

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]
}
ref(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"}
required(model, name)

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]

}

title(model, title)

Sets the title of the schema

Example

iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.title("User")
%PhoenixSwagger.Schema{title: "User"}
type(model, type)

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]}
unique_items(model, unique?)

Boolean that when true, requires each item of an array schema to be unique.

Example

iex> alias PhoenixSwagger.Schema
...> %Schema{type: :array}
...> |> Schema.unique_items(true)
%PhoenixSwagger.Schema{type: :array, uniqueItems: true}

Macros

new(block)

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]
}
properties(model, block)

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]
}