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

Sets the description for the schema.

Examples

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

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

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
}

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}

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}

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}

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}

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}

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}

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

@spec 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.

Examples

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

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

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

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

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}