PhoenixSpectral.OpenAPIController (phoenix_spectral v0.5.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
  • :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)