Controller for serving OpenAPI specifications in JSON format or Redoc UI.

Serving the JSON spec

Add a route in your router by passing the spec module to this controller:

get "/openapi.json", Oaskit.SpecController, spec: MyAppWeb.ApiSpec

Alternatively, you can automatically serve the spec that provided with the spec provider plug by giving the spec: true option or by replacing the options with :show. The route needs to be scoped with the appropriate pipeline:

defmodule MyAppWeb.Router do
  use Phoenix.Router

  pipeline :api do
    plug Oaskit.Plugs.SpecProvider, spec: MyAppWeb.ApiSpec
  end

  scope "/" do
    pipe_through :api

    get "/openapi.json", Oaskit.SpecController, :show
    # OR
    get "/openapi.json", Oaskit.SpecController, spec: true
  end
end

This will serve your OpenAPI specification at /openapi.json. Add ?pretty=1 in the URL for easier debugging.

The controller works with any spec module that implements the Oaskit behavior. Note that if your spec is obtained from a static file, you don't really need that controller and can just serve that file.

Showing Redoc

Redoc is a simple documentation generator that will display an OpenAPI specification in a nice way. It does not allow to test the routes though.

Pass the absolute URL path to the controller with the :redoc option, and optionally a redoc configuration object:

get "/redoc", Oaskit.SpecController, redoc: "/url/to/openapi.json"
get "/redoc", Oaskit.SpecController,
  redoc: "/generated/openapi.json",
  redoc_config: %{
    "minCharacterLengthToInitSearch" => 1,
    "hideDownloadButtons" => true
  }

Other options

A :resp_headers option can be provided to set the response headers for the JSON or Redoc routes.

pipeline :api do
  get "/openapi.json", Oaskit.SpecController,
    spec: MyApp.ApiSpec,
    resp_headers: %{"access-control-allow-origin" => "*"}
end