AshOaskit.Generators.Generator (AshOasKit v0.2.1)

Main OpenAPI specification generator.

This module orchestrates the generation of complete OpenAPI specifications from Ash domains, delegating to specialized builders for each section.

Overview

The generator produces a complete OpenAPI document with:

openapi - Version string ("3.0.3" or "3.1.0")
info - API metadata (title, version, description)
servers - Server URLs for the API
paths - All operations organized by path
components - Reusable schemas
tags - Resource groupings
security - Optional security requirements

Module Delegation

The generator delegates to focused builders:

InfoBuilder - Info object, servers, and tags
PathBuilder - Paths and operations
PhoenixIntrospection - Controller route extraction (optional)
ComponentsBuilder - Schemas (internal to this module)

Usage

spec = Generator.generate([MyApp.Domain], version: "3.1", title: "My API")

Options

Option	Type	Description
`:version`	`"3.0"` or `"3.1"`	OpenAPI version (required)
`:title`	string	API title
`:api_version`	string	API version
`:description`	string	API description
`:terms_of_service`	string	Terms URL
`:contact`	map	Contact info
`:license`	map	License info
`:servers`	list	Server URLs
`:security`	list	Security requirements
`:router`	module	Phoenix router for controller introspection
`:modify_open_api`	function or MFA	Post-processing hook for spec customization

Summary

Types

opts()

Functions

build_components(domains, opts)

Builds components (schemas) from domains.

generate(domains, opts)

Generate an OpenAPI specification from the given domains.

Types

opts()

@type opts() :: keyword()

Functions

build_components(domains, opts)

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

Builds components (schemas) from domains.

Generates schema definitions for all resources in the provided domains, using the appropriate type mapper for the OpenAPI version.

Parameters

domains - List of Ash domain modules
opts - Options including :version

Returns

A components object containing schemas.

generate(domains, opts)

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

Generate an OpenAPI specification from the given domains.

Parameters

domains - List of Ash domain modules to include in the spec
opts - Generation options (see module docs)

Returns

A complete OpenAPI specification as a map.

Examples

iex> Generator.generate([MyApp.Blog], version: "3.1")
%{
  "openapi" => "3.1.0",
  "info" => %{"title" => "API", "version" => "1.0.0"},
  "servers" => [%{"url" => "/"}],
  "paths" => %{...},
  "components" => %{"schemas" => %{...}},
  "tags" => [%{"name" => "Post"}, ...]
}

# With Phoenix router for controller routes
iex> Generator.generate([MyApp.Blog], version: "3.1", router: MyAppWeb.Router)

# With post-processing hook
iex> Generator.generate([MyApp.Blog],
...>   version: "3.1",
...>   modify_open_api: fn spec -> Map.put(spec, "x-custom", true) end
...> )