Rolodex v0.6.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

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

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. Data passed into to the schema/1 macro will be parsed by Rolodex.Field.new/1

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

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. Data passed into to the schema/1 macro will be parsed by Rolodex.Field.new/1.

Examples

# Request body is a list, where each item is a MySchema
content "application/json" do
  schema [MySchema]
end

# Request body is a MySchema
content "application/json" do
  content MySchema
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}
        ]
      }
    }
  }
}