AshOaskit.Controller (AshOasKit v0.2.0)

View Source

Phoenix controller for serving OpenAPI specifications.

Deprecated

This controller regenerates the spec on every request and reads its configuration from the application environment. Define a spec module with use AshOaskit and serve it through Oaskit.SpecController instead — it is cached, explicit, and gains the Redoc UI:

defmodule MyAppWeb.ApiSpec do
  use AshOaskit, domains: [MyApp.Blog], title: "My API"
end

# In your router
get "/openapi.json", Oaskit.SpecController, spec: MyAppWeb.ApiSpec
get "/redoc", Oaskit.SpecController, redoc: "/openapi.json"

This module will be removed in 0.3.0.

This module provides Plug-compatible controller actions for serving OpenAPI specs directly from your Phoenix application.

Usage

Add routes in your Phoenix router:

scope "/api" do
  get "/openapi.json", AshOaskit.Controller, :spec
  get "/openapi-3.0.json", AshOaskit.Controller, :spec_30
  get "/openapi-3.1.json", AshOaskit.Controller, :spec_31
end

Configuration

Configure domains and metadata in your application config:

config :ash_oaskit,
  domains: [MyApp.Blog, MyApp.Accounts],
  title: "My API",
  api_version: "1.0.0",
  description: "My awesome API",
  version: "3.1"

Per-Route Options

Override configuration per-route using Phoenix's private assigns:

get "/api/openapi.json", AshOaskit.Controller, :spec,
  private: %{ash_oaskit: [
    domains: [MyApp.Blog],
    title: "Blog API"
  ]}

Response Format

All actions return JSON with application/json content type and pretty-printed output for readability.

Actions

  • spec/2 - Serves the spec using the configured default version
  • spec_30/2 - Always serves an OpenAPI 3.0 spec
  • spec_31/2 - Always serves an OpenAPI 3.1 spec

Summary

Functions

spec(conn, _) deprecated

Serve the OpenAPI spec using the configured default version.

spec_30(conn, _) deprecated

Serve an OpenAPI 3.0 spec.

spec_31(conn, _) deprecated

Serve an OpenAPI 3.1 spec.

Functions

spec(conn, _)

This function is deprecated. Use Oaskit.SpecController with a `use AshOaskit` spec module. 
@spec spec(Plug.Conn.t(), map()) :: Plug.Conn.t()

Serve the OpenAPI spec using the configured default version.

spec_30(conn, _)

This function is deprecated. Use Oaskit.SpecController with a `use AshOaskit` spec module. 
@spec spec_30(Plug.Conn.t(), map()) :: Plug.Conn.t()

Serve an OpenAPI 3.0 spec.

spec_31(conn, _)

This function is deprecated. Use Oaskit.SpecController with a `use AshOaskit` spec module. 
@spec spec_31(Plug.Conn.t(), map()) :: Plug.Conn.t()

Serve an OpenAPI 3.1 spec.