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

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

You can also replace :show by spec: MyAppWeb.ApiSpec when calling the controller

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
  }