open_api_spex v3.6.0 OpenApiSpex.Controller View Source
Generation of OpenAPI documentation via ExDoc documentation and tags.
Supported OpenAPI fields
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.
operation_id
The action's operation_id
can be set explicitly using a @doc
tag.
If no operation_id
is specified, it will default to the action's module path: Module.Name.function_name
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.request_body/3
or
OpenApiSpex.Operation.request_body/4
, respectively.
@doc request_body: {
"CartUpdateRequest",
"application/vnd.api+json",
CartUpdateRequest,
required: true
}
tags
Tags 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