Settings View Source OpenApiSpex.Controller (open_api_spex v3.20.0)

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