Rolodex v0.6.0 Rolodex.Response

Exposes functions and macros for defining reusable responses.

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

  • response/2 - for declaring a response
  • desc/1 - for setting an (optional) response description
  • content/2 - for defining a response 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) response example for a content type

It also exposes the following functions:

Link to this section Summary

Functions

Defines a response shape for the given content type key

Sets a description for the response

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 Response and collects any nested references to any Schemas within. See Rolodex.Field.get_refs/1 for more info

Sets headers to be included in the response. You can use a shared headers ref defined via Rolodex.Headers, or just pass in a bare map or keyword list

Determines if an arbitrary item is a module that has defined a reusable response via Rolodex.Response macros

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

Sets a schema for the current response content type. Data passed into to the schema/1 macro will be parsed by Rolodex.Field.new/1

Sets a collection of schemas for the current response content type

Serializes the Rolodex.Response metadata into a formatted map

Link to this section Functions

Link to this macro

content(key, opts) (macro)

Defines a response shape for the given content type key

Accepts

  • key - a valid content-type key
  • block - metadata about the response shape for this content type
Link to this macro

desc(str) (macro)

Sets a description for the response

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 Response and collects any nested references to any Schemas within. See Rolodex.Field.get_refs/1 for more info.

Link to this macro

headers(metadata) (macro)

Sets headers to be included in the response. You can use a shared headers ref defined via Rolodex.Headers, or just pass in a bare map or keyword list.

Examples

# Shared headers module
defmodule MyResponse do
  use Rolodex.Response

  response "MyResponse" do
    headers MyResponseHeaders
  end
end

# Headers defined in place
defmodule MyResponse do
  use Rolodex.Response

  response "MyResponse" do
    headers %{
      "X-Pagination" => %{
        type: :integer,
        description: "Pagination information"
      }
    }
  end
end
Link to this function

is_response_module?(mod)
is_response_module?(any()) :: boolean()

Determines if an arbitrary item is a module that has defined a reusable response via Rolodex.Response macros

Example

iex> defmodule SimpleResponse do
...>   use Rolodex.Response
...>   response "SimpleResponse" do
...>     content "application/json" do
...>       schema MySchema
...>     end
...>   end
...> end
iex>
iex> # Validating a response module
iex> Rolodex.Response.is_response_module?(SimpleResponse)
true
iex> # Validating some other module
iex> Rolodex.Response.is_response_module?(OtherModule)
false
Link to this macro

response(name, opts) (macro)

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

Accept

  • name - the response name
  • block - response shape definitions

Example

defmodule MyResponse do
  use Rolodex.Response

  response "MyResponse" do
    desc "A demo response with multiple content types"

    content "application/json" do
      schema MyResponseSchema

      example :response, %{foo: "bar"}
      example :other_response, %{bar: "baz"}
    end

    content "foo/bar" do
      schema AnotherResponseSchema
      example :response, %{foo: "bar"}
    end
  end
end
Link to this macro

schema(mod) (macro)

Sets a schema for the current response content type. Data passed into to the schema/1 macro will be parsed by Rolodex.Field.new/1.

Examples

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

# Response 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 collection of schemas for the current response content type.

Examples

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

# Response 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.Response metadata into a formatted map.

Example

iex> defmodule MySimpleSchema do
...>   use Rolodex.Schema
...>
...>   schema "MySimpleSchema" do
...>     field :id, :uuid
...>   end
...> end
iex>
iex> defmodule MyResponse do
...>   use Rolodex.Response
...>
...>   response "MyResponse" do
...>     desc "A demo response"
...>
...>     headers %{"X-Rate-Limited" => :boolean}
...>
...>     content "application/json" do
...>       schema MySimpleSchema
...>       example :response, %{id: "123"}
...>     end
...>
...>     content "application/json-list" do
...>       schema [MySimpleSchema]
...>       example :response, [%{id: "123"}]
...>       example :another_response, [%{id: "234"}]
...>     end
...>   end
...> end
iex>
iex> Rolodex.Response.to_map(MyResponse)
%{
  desc: "A demo response",
  headers: %{
    "X-Rate-Limited" => %{type: :boolean}
  },
  content: %{
    "application/json" => %{
      examples: %{
        response: %{id: "123"}
      },
      schema: %{
        type: :ref,
        ref: Rolodex.ResponseTest.MySimpleSchema
      }
    },
    "application/json-list" => %{
      examples: %{
        response: [%{id: "123"}],
        another_response: [%{id: "234"}],
      },
      schema: %{
        type: :list,
        of: [
          %{type: :ref, ref: Rolodex.ResponseTest.MySimpleSchema}
        ]
      }
    }
  }
}