Rolodex v0.10.1 Rolodex.RequestBody

Exposes functions and macros for defining reusable request bodies.

It exposes the following macros, which when used together will setup a request body:

  • request_body/2 - for declaring a request body
  • desc/1 - for setting an (optional) request body description
  • content/2 - for defining a request body shape for a specific content type
  • schema/1 and schema/2 - for defining the shape for a content type
  • example/2 - for defining an (optional) request body example for a content type

It also exposes the following functions:

Link to this section Summary

Functions

Defines a request body shape for the given content type key

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

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

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

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

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

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

Sets a schema of a collection type

Serializes the Rolodex.RequestBody metadata into a formatted map

Link to this section Functions

Link to this macro

content(key, opts) (macro)

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

desc(str) (macro)

Sets a description for the request body

Link to this macro

example(name, example_body) (macro)

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

field(identifier, type, opts \\ []) (macro)

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

get_refs(mod)
get_refs(module()) :: [module()]

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

Link to this function

is_request_body_module?(mod)
is_request_body_module?(any()) :: boolean()

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

partial(mod) (macro)

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

request_body(name, opts) (macro)

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

schema(mod) (macro)

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

schema(collection_type, opts) (macro)

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

to_map(mod)
to_map(module()) :: map()

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