open_api_spex v3.5.1 OpenApiSpex.Controller View Source
Generation of OpenAPI documentation via ExDoc documentation and tags.
Supported OpenAPI fields
Attribute operationId
is automatically provided by the implementation
and cannot be changed in any way. It is constructed as Module.Name.function_name
in the same way as function references in backtraces.
description
and summary
Description of endpoint will be filled with documentation string in the same
manner as ExDocs, so first line will be used as a summary
and whole
documentation will be used as description
field.
parameters
Parameters of the endpoint are defined by :parameters
tag which should be
map or keyword list that is formed as:
[
param_name: definition
]
Where definition
is OpenApiSpex.Parameter.t()
structure or map or keyword
list that accepts the same arguments.
responses
Responses are controlled by :responses
tag. Responses must be defined as
a map or keyword list in form of:
%{
200 => {"Response name", "application/json", schema},
:not_found => {"Response name", "application/json", schema}
}
Where atoms are the same as Plug.Conn.Status.code/1
values.
requestBody
Controlled by :request_body
parameter and is defined as a tuple in form
{description, mime, schema}
or {description, mime, schema, opts} that matches the arguments of [
OpenApiSpex.Operation.requestbody/3](OpenApiSpex.Operation.html#request_body/3) or [
OpenApiSpex.Operation.requestbody/4](OpenApiSpex.Operation.html#request_body/4), respectively. ``` @doc request_body: { "CartUpdateRequest", "application/vnd.api+json", CartUpdateRequest, required: true } ``` ###
tagsTags are controlled by
:tags` attribute. In contrast to other attributes, this
one will also inherit all tags defined as a module documentation attributes.
## Example
```
defmodule FooController do
use MyAppWeb, :controller
use #{inspect(__MODULE)}
@moduledoc tags: ["Foos"]
@doc """
Endpoint summary
Endpoint description...
"""
@doc parameters: [
id: [in: :path, type: :string, required: true]
],
request_body: {"Request body to update Foo", "application/json", FooUpdateBody, required: true},
responses: [
ok: {"Foo document", "application/json", FooSchema}
]
def update(conn, %{id: id}) do
foo_params = conn.body_params
# …
end
end
```