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

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.

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 MyResponse do
  use Rolodex.Response

  response "MyResponse" 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 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. If the macro is called multiple times, all headers passed in will be merged together in the docs result.

Examples

# Shared headers module
defmodule MyResponse do
  use Rolodex.Response

  response "MyResponse" do
    headers MyResponseHeaders
    headers MyAdditionalResponseHeaders
  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

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

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 MyResponse do
  use Rolodex.Response

  response "MyResponse" do
    content "application/json" do
      schema do
        field :id, :uuid
        partial PaginationParams
      end
    end
  end
end

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

Sets a schema for the current response 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 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

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