open_api_spex v3.5.0 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 :body
parameter and is defined as a tuple in form
{description, mime, schema}
.
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 #{inspect(__MODULE__)}
@moduledoc tags: ["Foos"]
@doc """
Endpoint summary
More docs
"""
@doc [
parameters: [
id: [in: :path, type: :string, required: true]
],
responses: [
ok: {"Foo document", "application/json", FooSchema}
]
]
def show(conn, %{id: id}) do
# …
end
end