AshOaskit.OpenApi (AshOasKit v0.4.0)

Generates and validates OpenAPI documents for Ash domains.

Most applications should call the equivalent functions on AshOaskit or define a cached spec module with use AshOaskit. This lower-level module owns version selection and Oaskit normalization.

Version Selection

spec(opts)
     │
     ├── version: "3.1" ──▶ V31.generate/2
     │
     └── version: "3.0" ──▶ V30.generate/2

Pass :version explicitly or configure config :ash_oaskit, version: "3.1". OpenAPI 3.1 is the default.

Example

spec = AshOaskit.OpenApi.spec(domains: [MyApp.Blog])
json = Oaskit.SpecDumper.to_json!(spec, pretty: true)

Version-Specific Differences

Feature	OpenAPI 3.0	OpenAPI 3.1
Nullable	`nullable: true`	`type: ["string", "null"]`
Examples	`example` only	`example` and `examples`
JSON Schema	Extended Wright Draft 00 subset	Draft 2020-12 aligned

Summary

Functions

spec(opts \\ [])

Generate an OpenAPI specification for the given domains.

spec_30(opts \\ [])

Generate an OpenAPI 3.0 specification.

spec_31(opts \\ [])

Generate an OpenAPI 3.1 specification.

to_map(spec)

Convert a spec to a JSON-encodable map.

validate(spec)

Validate an OpenAPI specification through Oaskit.

validate!(spec)

Validate an OpenAPI specification through Oaskit.

Functions

spec(opts \\ [])

@spec spec(keyword()) :: map()

Generate an OpenAPI specification for the given domains.

The generated spec is normalized through Oaskit.normalize_spec!/1 to ensure canonical form with proper key ordering and structure.

Options

:domains - List of Ash domains to include (required)
:version - OpenAPI version: "3.0" or "3.1" (default from config or "3.1")
:title - API title
:api_version - API version string
:servers - List of server URLs
:description - API description

Examples

iex> spec = AshOaskit.OpenApi.spec(domains: [AshOaskit.Test.Blog])
...> spec["openapi"]
"3.1.0"

iex> spec = AshOaskit.OpenApi.spec(domains: [AshOaskit.Test.Blog], version: "3.0")
...> spec["openapi"]
"3.0.3"

iex> spec = AshOaskit.OpenApi.spec(domains: [AshOaskit.Test.Blog], title: "Test API")
...> spec["info"]["title"]
"Test API"

spec_30(opts \\ [])

@spec spec_30(keyword()) :: map()

Generate an OpenAPI 3.0 specification.

Shorthand for spec(Keyword.put(opts, :version, "3.0")).

spec_31(opts \\ [])

@spec spec_31(keyword()) :: map()

Generate an OpenAPI 3.1 specification.

Shorthand for spec(Keyword.put(opts, :version, "3.1")).

to_map(spec)

@spec to_map(map()) :: map()

Convert a spec to a JSON-encodable map.

Handles Oaskit structs by normalizing through Oaskit and encoding via Oaskit.SpecDumper to produce a plain map.

validate(spec)

@spec validate(map()) :: {:ok, struct()} | {:error, term()}

Validate an OpenAPI specification through Oaskit.

Returns {:ok, %Oaskit.Spec.OpenAPI{}} on success or {:error, error} on failure. The spec should already be normalized (as returned by spec/1).

Examples

iex> spec = AshOaskit.OpenApi.spec(domains: [AshOaskit.Test.Blog])
...> {:ok, validated} = AshOaskit.OpenApi.validate(spec)
...> validated.__struct__
Oaskit.Spec.OpenAPI

validate!(spec)

@spec validate!(map()) :: struct()

Validate an OpenAPI specification through Oaskit.

Returns %Oaskit.Spec.OpenAPI{} on success or raises on failure. The spec should already be normalized (as returned by spec/1).

Examples

iex> spec = AshOaskit.OpenApi.spec(domains: [AshOaskit.Test.Blog])
...> validated = AshOaskit.OpenApi.validate!(spec)
...> validated.__struct__
Oaskit.Spec.OpenAPI