AshOaskit.Router (AshOasKit v0.2.0)

View Source

Router macro for serving OpenAPI specs with minimal configuration.

Works with both Phoenix Router and Plug.Router. Automatically detects the router type and generates appropriate routes.

Pass a spec module defined with use AshOaskit to serve it through Oaskit.SpecController, gaining persistent_term caching and an optional Redoc UI:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  use AshOaskit.Router,
    spec: MyAppWeb.ApiSpec,
    open_api: "/openapi",
    redoc: "/redoc"
end

Generates:

GET /openapi.json   -> the spec served by Oaskit.SpecController
GET /redoc          -> Redoc UI rendering /openapi.json

To serve OpenAPI 3.0 and 3.1 side by side, pass {suffix, module} pairs (the first entry also serves as the default at open_api.json):

use AshOaskit.Router,
  spec: [{"3.1", MyAppWeb.ApiSpecV31}, {"3.0", MyAppWeb.ApiSpecV30}],
  open_api: "/openapi"

GET /openapi.json      -> 3.1 spec (first entry)
GET /openapi/3.1.json  -> 3.1 spec
GET /openapi/3.0.json  -> 3.0 spec

Spec mode options

  • :spec - A spec module (use AshOaskit) or list of {suffix, module} pairs (required for this mode)
  • :open_api - Base path for OpenAPI endpoints (required)
  • :redoc - Path to serve the Redoc UI (optional)
  • :redoc_spec_url - Absolute URL path Redoc fetches the spec from. Defaults to "#{open_api}.json" — set this when the router macro runs inside a scope with a path prefix, because Redoc fetches by absolute URL (e.g. redoc_spec_url: "/api/openapi.json")
  • :redoc_config - Redoc configuration map (optional)
  • :resp_headers - Response headers map for the JSON endpoints (optional, e.g. CORS headers)

Legacy domains mode (deprecated)

Passing :domains directly is deprecated: the spec is regenerated on every request. Define a spec module with use AshOaskit and switch to the :spec option.

use AshOaskit.Router,
  domains: [MyApp.Blog, MyApp.Accounts],
  open_api: "/docs/openapi",
  title: "My API",
  version: "1.0.0"

Legacy mode options

  • :domains - List of Ash domains to include (required)
  • :open_api - Base path for OpenAPI endpoints (required)
  • :title - API title (default: "API")
  • :version - API version string (default: "1.0.0")
  • :description - API description (optional)
  • :openapi_versions - List of OpenAPI versions to serve (default: ["3.0", "3.1"])
  • :default_version - Default OpenAPI version (default: "3.1")
  • :formats - Output formats (default: [:json])
  • :servers - List of server URLs or server objects (optional)
  • :router - Phoenix router module for controller introspection (optional)
  • :modify_open_api - Post-processing function for spec customization (optional)
  • :spec_builder - Custom SpecBuilder module (default: AshOaskit.SpecBuilder.Default)