Defines a request body shape for the given content type key

Accepts

• key - a valid content-type key
• block - metadata about the request body shape for this content type

Sets a description for the request body

Sets an example for the content type. This macro can be used multiple times within a content type block to allow multiple examples.

Accepts

• name - a name for the example
• body - a map, which is the example data

Adds a new field to the schema when defining a schema inline via macros. See Rolodex.Field for more information about valid field metadata.

Accepts

• identifier - field name
• type - either an atom or another Rolodex.Schema module
• opts - a keyword list of options, looks for desc and of (for array types)

Example

defmodule MyRequestBody do
  use Rolodex.RequestBody

  request_body "MyRequestBody" do
    content "application/json" do
      schema do
        # Atomic field with no description
        field :id, :uuid

        # Atomic field with a description
        field :name, :string, desc: "The object's name"

        # A field that refers to another, nested object
        field :other, OtherSchema

        # A field that is an array of items of one-or-more types
        field :multi, :list, of: [:string, OtherSchema]

        # You can use a shorthand to define a list field, the below is identical
        # to the above
        field :multi, [:string, OtherSchema]

        # A field that is one of the possible provided types
        field :any, :one_of, of: [:string, OtherSchema]
      end
    end
  end
end

Traverses a serialized Request Body and collects any nested references to any Schemas within. See Rolodex.Field.get_refs/1 for more info.

Determines if an arbitrary item is a module that has defined a reusable request body via Rolodex.RequestBody macros.

Example

iex> defmodule SimpleRequestBody do
...>   use Rolodex.RequestBody
...>
...>   request_body "SimpleRequestBody" do
...>     content "application/json" do
...>       schema MySchema
...>     end
...>   end
...> end
iex>
iex> # Validating a request body module
iex> Rolodex.RequestBody.is_request_body_module?(SimpleRequestBody)
true
iex> # Validating some other module
iex> Rolodex.RequestBody.is_request_body_module?(OtherModule)
false

Adds a new partial to the schema when defining a schema inline via macros. A partial is another schema that will be serialized and merged into the top-level properties map for the current schema. Partials are useful for shared parameters used across multiple schemas. Bare keyword lists and maps that are parseable by Rolodex.Field are also supported.

Example

defmodule PaginationParams do
  use Rolodex.Schema

  schema "PaginationParams" do
    field :page, :integer
    field :page_size, :integer
    field :total_pages, :integer
  end
end

defmodule MyRequestBody do
  use Rolodex.RequestBody

  request_body "MyRequestBody" do
    content "application/json" do
      schema do
        field :id, :uuid
        partial PaginationParams
      end
    end
  end
end

Opens up the request body definition for the current module. Will name the request body and generate metadata for the request body based on macro calls within the provided block.

Accept

• name - the request body name
• block - request body shape definitions

Example

defmodule MyRequestBody do
  use Rolodex.RequestBody

  request_body "MyRequestBody" do
    desc "A demo request body with multiple content types"

    content "application/json" do
      schema MyRequestBodySchema

      example :request_body, %{foo: "bar"}
      example :other_request_body, %{bar: "baz"}
    end

    content "foo/bar" do
      schema AnotherRequestBodySchema
      example :request_body, %{foo: "bar"}
    end
  end
end

Sets a schema for the current request body content type. There are three ways you can define a schema for a content-type chunk:

1. You can pass in an alias for a reusable schema defined via Rolodex.Schema
2. You can define a schema inline via the same macro syntax used in Rolodex.Schema
3. You can define a schema inline via a bare map, which will be parsed with Rolodex.Field

Examples

# Via a reusable schema alias
content "application/json" do
  schema MySchema
end

# Can define a schema inline via the schema + field + partial macros
content "application/json" do
  schema do
    field :id, :uuid
    field :name, :string, desc: "The name"

    partial PaginationParams
  end
end

# Can provide a bare map, which will be parsed via [`Rolodex.Field`](Rolodex.Field.html)
content "application/json" do
  schema %{
    type: :object,
    properties: %{
      id: :uuid,
      name: :string
    }
  }
end

Sets a schema of a collection type.

Examples

# Request body is a list
content "application/json" do
  schema :list, of: [MySchema]
end

# Request body is one of the provided types
content "application/json" do
  schema :one_of, of: [MySchema, MyOtherSchema]
end

Serializes the Rolodex.RequestBody metadata into a formatted map.

Example

iex> defmodule MySimpleSchema do
...>   use Rolodex.Schema
...>
...>   schema "MySimpleSchema" do
...>     field :id, :uuid
...>   end
...> end
iex>
iex> defmodule MyRequestBody do
...>   use Rolodex.RequestBody
...>
...>   request_body "MyRequestBody" do
...>     desc "A demo request body"
...>
...>     content "application/json" do
...>       schema MySimpleSchema
...>       example :request_body, %{id: "123"}
...>     end
...>
...>     content "application/json-list" do
...>       schema [MySimpleSchema]
...>       example :request_body, [%{id: "123"}]
...>       example :another_request_body, [%{id: "234"}]
...>     end
...>   end
...> end
iex>
iex> Rolodex.RequestBody.to_map(MyRequestBody)
%{
  desc: "A demo request body",
  headers: [],
  content: %{
    "application/json" => %{
      examples: %{
        request_body: %{id: "123"}
      },
      schema: %{
        type: :ref,
        ref: Rolodex.RequestBodyTest.MySimpleSchema
      }
    },
    "application/json-list" => %{
      examples: %{
        request_body: [%{id: "123"}],
        another_request_body: [%{id: "234"}],
      },
      schema: %{
        type: :list,
        of: [
          %{type: :ref, ref: Rolodex.RequestBodyTest.MySimpleSchema}
        ]
      }
    }
  }
}