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 ```