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 bodydesc/1
- for setting an (optional) request body descriptioncontent/2
- for defining a request body shape for a specific content typeschema/1
andschema/2
- for defining the shape for a content typeexample/2
- for defining an (optional) request body example for a content type
It also exposes the following functions:
is_request_body_module?/1
- determines if the provided item is a module that has defined a reusable request bodyto_map/1
- serializes a request body module into a mapget_refs/1
- traverses a request body and searches for any nestedRolodex.Schema
refs within
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
content(key, opts) (macro)
Defines a request body shape for the given content type key
Accepts
key
- a valid content-type keyblock
- metadata about the request body shape for this content type
desc(str) (macro)
Sets a description for the request body
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 Request Body and collects any nested references to any
Schemas within. See Rolodex.Field.get_refs/1
for more info.
is_request_body_module?(mod)
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
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 nameblock
- 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
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
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
to_map(mod)
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}
]
}
}
}
}