PhoenixSwagger.Schema (phoenix_swagger v0.8.3) View Source

Struct and helpers for swagger schema.

Fields should reflect the swagger SchemaObject specification http://swagger.io/specification/#schemaObject

Link to this section 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.

Construct a new %Schema{} struct using the schema DSL.

Sets the x-nullable vendor extension property for the schema.

Restricts a string schema to match a regular expression, given as a string.

Defines multiple properties for a schema with a custom DSL syntax

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.

Link to this section Functions

Link to this function

additional_properties(model, bool_or_schema)

View Source

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"
}
Link to this function

description(model, desc)

View Source

Sets the description for the schema.

Example

iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.description("A user")
%PhoenixSwagger.Schema{description: "A user"}
Link to this function

discriminator(model, property_name)

View Source

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

}

Link to this function

exclusive_maximum(model, exclusive?)

View Source

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
}
Link to this function

exclusive_minimum(model, exclusive?)

View Source

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}
Link to this function

items(model, item_schema)

View Source

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}
Link to this function

max_length(model, value)

View Source

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}
Link to this function

max_properties(model, value)

View Source

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}
Link to this function

min_length(model, value)

View Source

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}
Link to this function

min_properties(model, value)

View Source

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}
Link to this function

multiple_of(model, number)

View Source

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}

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

Specs

nullable(
  %PhoenixSwagger.Schema{
    "$ref": term(),
    additionalProperties: term(),
    allOf: term(),
    default: term(),
    description: term(),
    discriminator: term(),
    enum: term(),
    example: term(),
    exclusiveMaximum: term(),
    exclusiveMinimum: term(),
    format: term(),
    items: term(),
    maxItems: term(),
    maxLength: term(),
    maxProperties: term(),
    maximum: term(),
    minItems: term(),
    minLength: term(),
    minProperties: term(),
    minimum: term(),
    multipleOf: term(),
    pattern: term(),
    properties: term(),
    required: term(),
    title: term(),
    type: term(),
    uniqueItems: term(),
    "x-nullable": term()
  },
  maybe_boolean
) :: %PhoenixSwagger.Schema{
  "$ref": term(),
  additionalProperties: term(),
  allOf: term(),
  default: term(),
  description: term(),
  discriminator: term(),
  enum: term(),
  example: term(),
  exclusiveMaximum: term(),
  exclusiveMinimum: term(),
  format: term(),
  items: term(),
  maxItems: term(),
  maxLength: term(),
  maxProperties: term(),
  maximum: term(),
  minItems: term(),
  minLength: term(),
  minProperties: term(),
  minimum: term(),
  multipleOf: term(),
  pattern: term(),
  properties: term(),
  required: term(),
  title: term(),
  type: term(),
  uniqueItems: term(),
  "x-nullable": term()
}
when maybe_boolean: true | false | nil

Sets the x-nullable vendor extension property for the schema.

## Example

iex> alias PhoenixSwagger.Schema ...> %Schema{type: :string} |> Schema.nullable(true) %Schema{

type: :string,
'x-nullable': true

}

Link to this function

pattern(model, regex_pattern)

View Source

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}$"}
Link to this macro

properties(model, block)

View Source (macro)

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]
}
Link to this function

property(model, name, type_or_schema, description \\ nil, opts \\ [])

View Source

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]}
Link to this function

unique_items(model, unique?)

View Source

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}