AshOaskit.PhoenixIntrospection (AshOasKit v0.2.0)

Extracts OpenAPI paths from Phoenix router for controllers implementing the AshOaskit.OpenApiController behaviour.

This module enables AshOaskit to include non-Ash controller routes in the OpenAPI specification. Only controllers that explicitly implement the OpenApiController behaviour are included.

Usage

This module is used internally by AshOaskit.Generators.PathBuilder when a :router option is provided:

paths = PathBuilder.build_paths(domains, router: MyAppWeb.Router)

How It Works

Calls Phoenix.Router.routes/1 to get all routes
Filters to only include routes where the plug (controller) implements the AshOaskit.OpenApiController behaviour
For each matching route, calls controller.openapi_operations/0 to get the operation metadata
Converts routes to OpenAPI path items

Route Structure

Phoenix routes have the following structure:

%{
  path: "/api/health",
  verb: :get,
  plug: MyAppWeb.HealthController,
  plug_opts: :index
}

This is converted to OpenAPI format:

%{
  "/api/health" => %{
    "get" => %{
      operationId: "MyAppWeb.HealthController.index",
      summary: "Health check",
      responses: %{"200" => %{description: "Success"}}
    }
  }
}

Summary

Functions

extract_routes(router)

Extracts routes from a Phoenix router that implement OpenApiController.

extract_tags(router)

Extracts unique tags from controllers implementing OpenApiController.

routes_to_paths(routes)

Converts extracted routes to OpenAPI paths format.

Functions

extract_routes(router)

@spec extract_routes(module()) :: [map()]

Extracts routes from a Phoenix router that implement OpenApiController.

Parameters

router - A Phoenix router module

Returns

A list of route info maps with path, verb, controller, action, and operation.

Examples

PhoenixIntrospection.extract_routes(MyAppWeb.Router)
#=> [
#=>   %{
#=>     path: "/api/health",
#=>     verb: :get,
#=>     controller: MyAppWeb.HealthController,
#=>     action: :index,
#=>     operation: %{summary: "Health check", ...}
#=>   }
#=> ]

extract_tags(router)

@spec extract_tags(module()) :: [map()]

Extracts unique tags from controllers implementing OpenApiController.

Collects tags from all controllers that implement the openapi_tag/0 callback, or generates default tags from controller names.

Parameters

router - A Phoenix router module

Returns

A list of unique tag objects for the OpenAPI spec.

routes_to_paths(routes)

@spec routes_to_paths([map()]) :: map()

Converts extracted routes to OpenAPI paths format.

Groups routes by path and creates path items with operations keyed by HTTP method.

Parameters

routes - List of route info maps from extract_routes/1

Returns

A map of paths to path items, suitable for merging with Ash paths.

Examples

iex> routes = PhoenixIntrospection.extract_routes(MyAppWeb.Router)
...> PhoenixIntrospection.routes_to_paths(routes)
%{
  "/api/health" => %{
    "get" => %{operationId: "...", summary: "..."}
  }
}