View Source OpenApiSpex.Controller (open_api_spex v3.21.2)

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

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

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

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

Allows specifying the security scheme(s) required for this operation. See OpenApiSpex.Operation and OpenApiSpex.SecurityRequirement.

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