Rolodex v0.7.1 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 responsedesc/1
- for setting an (optional) response descriptioncontent/2
- for defining a response shape for a specific content typeschema/1
andschema/2
- for defining the shape for a content typeexample/2
- for defining an (optional) response example for a content type
It also exposes the following functions:
is_response_module?/1
- determines if the provided item is a module that has defined a reusable responseto_map/1
- serializes a response module into a mapget_refs/1
- traverses a response and searches for any nestedRolodex.Schema
refs within
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. If
the macro is called multiple times, all headers passed in will be merged together
in the docs result
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
content(key, opts) (macro)
Defines a response shape for the given content type key
Accepts
key
- a valid content-type keyblock
- metadata about the response shape for this content type
desc(str) (macro)
Sets a description for the response
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 examplebody
- a map, which is the example data
get_refs(mod)
Traverses a serialized Response and collects any nested references to any
Schemas within. See Rolodex.Field.get_refs/1
for more info.
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. 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
is_response_module?(mod)
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
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 nameblock
- 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
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
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
to_map(mod)
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}
]
}
}
}
}