PhoenixSpectral.OpenAPIController (phoenix_spectral v0.6.0)

Copy Markdown View Source

A plug-and-play Phoenix controller that serves the OpenAPI spec and Swagger UI.

Usage

defmodule MyAppWeb.OpenAPIController do
  use PhoenixSpectral.OpenAPIController,
    router: MyAppWeb.Router,
    title: "My API",
    version: "1.0.0"
end

Then add routes in your router:

get "/openapi", MyAppWeb.OpenAPIController, :show
get "/swagger", MyAppWeb.OpenAPIController, :swagger

Options

  • :router — (required) your Phoenix router module
  • :title — (required) API title for the OpenAPI spec
  • :version — (required) API version string
  • :summary — (optional) short summary of the API
  • :description — (optional) longer description of the API
  • :terms_of_service — (optional) URL to the terms of service
  • :contact — (optional) contact map with :name, :url, :email
  • :license — (optional) license map with :name and optional :url, :identifier
  • :servers — (optional) list of server objects, each with :url and optional :description
  • :security_schemes — (optional) map of named security schemes, emitted under components.securitySchemes. This is what makes Swagger UI render the "Authorize" button. Each value is an OpenAPI Security Scheme Object, e.g. %{"api_key" => %{type: "apiKey", in: "header", name: "x-api-key"}}
  • :security — (optional) list of security requirement objects applied as the global default to every operation, e.g. [%{"api_key" => []}]. Each key should name a scheme declared in :security_schemes (the value holds required scopes, empty for apiKey/http schemes). This is passed through to the OpenAPI spec as-is — PhoenixSpectral does not validate it.
  • :openapi_url — URL path where the JSON spec is served, used by Swagger UI. Defaults to the path of this controller's :show route as declared in the router (scope prefixes included). Set explicitly to use a different path.
  • :cache — when true, the generated JSON is stored in :persistent_term after the first request and served from there on subsequent requests (default: false)