AshOaskit.Generators.PathBuilder (AshOasKit v0.2.0)

OpenAPI paths and operations builder.

This module generates the paths section of OpenAPI specifications, converting Ash domain routes into OpenAPI path items with operations.

Overview

For each route defined in an Ash domain, this module generates:

Path item with the appropriate HTTP method
Operation with operationId, summary, tags
Parameters (path, query)
Request body (for POST/PATCH)
Response definitions

Route Types

Standard CRUD routes are mapped to HTTP methods:

Route Type	HTTP Method	Success Code
`:index`	GET	200
`:get`	GET	200
`:post`	POST	201
`:patch`	PATCH	200
`:delete`	DELETE	204

Relationship routes are delegated to AshOaskit.RelationshipRoutes.

Query Parameters

For GET operations, the following parameters are added:

filter - Field-specific filtering (from FilterBuilder)
sort - Sorting specification (from SortBuilder)
page - Pagination (offset, limit, cursor-based)
include - Relationship inclusion paths

Phoenix Controller Routes

When a :router option is provided, this module also includes routes from Phoenix controllers that implement AshOaskit.OpenApiController behaviour.

Usage

# Ash routes only
paths = PathBuilder.build_paths([MyApp.Domain], version: "3.1")

# Ash routes + Phoenix controller routes
paths = PathBuilder.build_paths([MyApp.Domain], version: "3.1", router: MyAppWeb.Router)

Summary

Functions

build_operation(route, opts)

Builds an operation object for a route.

build_paths(domains, opts)

Builds paths from domains and optionally from Phoenix router.

Types

opts()

@type opts() :: keyword()

Functions

build_operation(route, opts)

@spec build_operation(map(), opts()) :: map()

Builds an operation object for a route.

Parameters

route - The AshJsonApi route struct
opts - Options including :version

Returns

An OpenAPI operation object.

build_paths(domains, opts)

@spec build_paths([module()], opts()) :: map()

Builds paths from domains and optionally from Phoenix router.

Extracts all routes from the given domains and converts them to OpenAPI path items grouped by path. If a :router option is provided, also includes routes from Phoenix controllers implementing AshOaskit.OpenApiController.

Parameters

domains - List of Ash domain modules
opts - Options including:
- :version - OpenAPI version ("3.0" or "3.1")
- :router - Optional Phoenix router module for controller introspection

Returns

A map of path strings to path item objects.

Examples

iex> PathBuilder.build_paths([MyApp.Blog], version: "3.1")
%{
  "/posts" => %{
    "get" => %{...},
    "post" => %{...}
  },
  "/posts/{id}" => %{
    "get" => %{...},
    "patch" => %{...},
    "delete" => %{...}
  }
}

iex> PathBuilder.build_paths([MyApp.Blog], version: "3.1", router: MyAppWeb.Router)
%{
  "/posts" => %{...},
  "/api/health" => %{
    # From HealthController
    "get" => %{...}
  }
}