AshOaskit.Generators.InfoBuilder (AshOasKit v0.2.1)

View Source

OpenAPI Info object and server configuration builder.

This module handles the generation of the info and servers sections of OpenAPI specifications, as well as resource tags for organization.

Info Object

The Info object contains metadata about the API:

  • title - Required. The name of the API
  • version - Required. The version of the API document
  • description - Optional. Description of the API
  • termsOfService - Optional. URL to terms of service
  • contact - Optional. Contact information object
  • license - Optional. License information object

Servers

The servers array specifies base URLs for the API:

# Simple URL string
servers: ["https://api.example.com"]

# Full server object
servers: [%{
  "url" => "https://api.example.com",
  "description" => "Production server"
}]

Tags

Tags are generated from domain resources and used to group operations in documentation tools like Swagger UI.

Usage

info = InfoBuilder.build_info(title: "My API", api_version: "2.0")
servers = InfoBuilder.build_servers(servers: ["https://api.example.com"])
tags = InfoBuilder.build_tags([MyApp.Domain])

Summary

Types

opts()

Functions

build_info(opts)

Builds the Info object for the OpenAPI spec.

build_servers(opts)

Builds servers array from options.

build_tags(domains)

Builds tags from domain resources.

Types

opts()

@type opts() :: keyword()

Functions

build_info(opts)

@spec build_info(opts()) :: map()

Builds the Info object for the OpenAPI spec.

Options

  • :title - API title (defaults to application config or "API")
  • :api_version - API version string (defaults to "1.0.0")
  • :description - Optional description
  • :terms_of_service - Optional terms of service URL
  • :contact - Optional contact information map
  • :license - Optional license information map

Returns

A map conforming to the OpenAPI Info Object specification.

Examples

iex> InfoBuilder.build_info(title: "Pet Store", api_version: "1.0.0")
%{"title" => "Pet Store", "version" => "1.0.0"}

iex> InfoBuilder.build_info(title: "API", description: "My API")
%{"title" => "API", "version" => "1.0.0", "description" => "My API"}

build_servers(opts)

@spec build_servers(opts()) :: [map()]

Builds servers array from options.

Accepts either simple URL strings or full server objects with url, description, and variables.

Options

  • :servers - List of server URLs or server objects

Returns

A list of server objects. Defaults to [%{"url" => "/"}] if not specified.

Examples

iex> InfoBuilder.build_servers([])
[%{"url" => "/"}]

iex> InfoBuilder.build_servers(servers: ["https://api.example.com"])
[%{"url" => "https://api.example.com"}]

build_tags(domains)

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

Builds tags from domain resources.

Each resource in the domains generates a tag, which is used to group related operations in documentation.

Parameters

  • domains - List of Ash domain modules

Returns

A list of tag objects with name field.

Examples

iex> InfoBuilder.build_tags([MyApp.Blog])
[%{"name" => "Post"}, %{"name" => "Comment"}]