PhoenixSwagger.Schema (phoenix_swagger v0.8.3) View Source

Struct and helpers for swagger schema.

Fields should reflect the swagger SchemaObject specification.

See 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.

Used to combine multiple schemas, requiring a value to conform to all schemas.

Construct an array schema, where the array items schema is a ref to the given name.

Sets the default value for the schema.

Sets the description for the schema.

Specifies the name of a property that identifies the polymorphic schema for a JSON object.

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.

Boolean indicating that value for minimum is excluded from the valid range.

Sets the format of a Schema with type: :string.

Sets the schema/s for the items of an array.

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.

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.

Examples

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

Examples

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.

Examples

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.

Examples

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.

Examples

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

Examples

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.

Examples

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.

Examples

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

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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(),
    readOnly: 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(),
  readOnly: 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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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