View Source OpenApiSpex.Controller (open_api_spex v3.18.3)
Generation of OpenAPI documentation via ExDoc documentation and tags.
Note: For projects using Elixir releases, there is an issue that
potentially breaks OpenApiSpex's integration with your application. Please use OpenApiSpex.ControllerSpecs
instead.
supported-openapi-fields
Supported OpenAPI fields
description-and-summary
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 the rest of it
will be used as description
field.
operation_id
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
Parameters of the endpoint are defined by :parameters
tag which should be
map or list that is formed as:
[
param_name: definition
]
# or
[
structure_definition
]
Where definition
is map or keyword list that accepts the same arguments.
Where structure_definition
is OpenApiSpex.Parameter.t()
or OpenApiSpex.Reference.t()
structure
that accepts the same arguments.
Example:
@doc parameters: [
group_id: [in: :path, type: :integer, description: "Group ID", example: 1]
]
or
@doc parameters: [
%OpenApiSpex.Parameter{
in: :path,
name: :group_id,
description: "Group ID",
schema: %Schema{type: :integer},
required: true,
example: 1
}
]
or
@doc parameters: [
"$ref": "#/components/parameters/group_id"
# or
%OpenApiSpex.Reference{"$ref": "#/components/parameters/group_id"}
]
responses
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}
}
Or:
[
ok: {"Response name", "application/json", schema},
not_found: {"Response name", "application/json", schema}
]
If a response has no body, the definition may be simplified further:
[
no_content: "Empty response"
]
For each key in the key-value list of map, either an HTTP status code can be used or its atom equivalent.
The full set of atom keys are defined in Plug.Conn.Status.code/1
.
requestbody
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
}
security
security
Allows specifying the security scheme(s) required for this operation. See
OpenApiSpex.Operation
and OpenApiSpex.SecurityRequirement
.
tags
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
Example
defmodule UserController do
@moduledoc tags: ["Users"]
use MyAppWeb, :controller
use OpenApiSpex.Controller
@doc """
Endpoint summary
Endpoint description...
"""
@doc parameters: [
id: [in: :path, type: :string, required: true]
],
request_body: {"Request body to update User", "application/json", UserUpdateBody, required: true},
responses: [
ok: {"User document", "application/json", UserSchema},
{302, "Redirect", "text/html", EmptyResponse, headers: %{"Location" => %Header{description: "Redirect Location"}}}
]
def update(conn, %{id: id}) do
user_params = conn.body_params
# …
end
end