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