AshOaskit.TagBuilder (AshOasKit v0.2.1)

Builds OpenAPI tags for organizing operations in the specification.

This module provides functions to generate tags and assign operations to tags based on different grouping strategies. Tags help organize operations in documentation tools like Swagger UI and Redoc.

Grouping Strategies

By Resource (Default)

Groups operations by the Ash resource they operate on:

Posts:
  - GET /posts
  - POST /posts
  - GET /posts/{id}
Comments:
  - GET /comments
  - POST /comments

By Domain

Groups operations by the Ash domain they belong to:

Blog:
  - GET /posts
  - POST /posts
  - GET /comments
Shop:
  - GET /products
  - POST /orders

By Custom Tag

Uses custom tags defined in the resource or domain configuration.

Configuration

Tag configuration can come from:

AshJsonApi.Domain.Info.tag/1 - Domain-level tag override
AshJsonApi.Domain.Info.group_by/1 - Grouping strategy
Resource name (default fallback)

Usage

# Build tags grouped by resource
AshOaskit.TagBuilder.build_tags(domains, group_by: :resource)

# Build tags grouped by domain
AshOaskit.TagBuilder.build_tags(domains, group_by: :domain)

# Get tag for an operation
AshOaskit.TagBuilder.operation_tag(route, group_by: :resource)

Summary

Functions

build_custom_tags(domains, include_descriptions \\ true)

Builds tags based on custom configuration.

build_domain_tags(domains, include_descriptions \\ true)

Builds tags based on domains.

build_resource_tags(domains, include_descriptions \\ true)

Builds tags based on resources (default grouping).

build_tag(name, description \\ nil, opts \\ [])

Builds a tag object with optional description and external docs.

build_tags(domains, opts \\ [])

Builds tags for the OpenAPI specification.

build_tags_with_docs(domains, opts \\ [])

Builds tags with external documentation links.

domain_tag_name(domain)

Extracts the tag name from a domain module.

get_default_grouping(list)

Gets the default grouping strategy for the given domains.

merge_tags(generated_tags, custom_tags)

Merges custom tags with generated tags.

operation_tag(route, opts \\ [])

Gets the tag name for an operation based on the route.

operation_tags(route, opts \\ [])

Gets tags for an operation (returns as a list for OpenAPI operation tags).

resource_tag_name(resource)

Extracts the tag name from a resource module.

Functions

build_custom_tags(domains, include_descriptions \\ true)

@spec build_custom_tags([module()], boolean()) :: [map()]

Builds tags based on custom configuration.

Uses tag configuration from AshJsonApi domain info if available, falls back to domain name.

Examples

iex> AshOaskit.TagBuilder.build_custom_tags([MyApp.Blog])
[%{name: "Custom Tag Name"}]

build_domain_tags(domains, include_descriptions \\ true)

@spec build_domain_tags([module()], boolean()) :: [map()]

Builds tags based on domains.

Each domain becomes a tag, and all resources in that domain share the tag.

Examples

iex> AshOaskit.TagBuilder.build_domain_tags([MyApp.Blog, MyApp.Shop])
[
  %{name: "Blog", description: "Blog domain operations"},
  %{name: "Shop", description: "Shop domain operations"}
]

build_resource_tags(domains, include_descriptions \\ true)

@spec build_resource_tags([module()], boolean()) :: [map()]

Builds tags based on resources (default grouping).

Each resource becomes a tag.

Examples

iex> AshOaskit.TagBuilder.build_resource_tags([MyApp.Blog])
[%{name: "Post"}, %{name: "Comment"}]

build_tag(name, description \\ nil, opts \\ [])

@spec build_tag(String.t(), String.t() | nil, keyword()) :: map()

Builds a tag object with optional description and external docs.

Options

:external_docs - External documentation URL and description.

Examples

iex> AshOaskit.TagBuilder.build_tag("Posts", "Operations for blog posts")
%{name: "Posts", description: "Operations for blog posts"}

iex> AshOaskit.TagBuilder.build_tag("Posts", nil,
...>   external_docs: %{url: "https://docs.example.com"}
...> )
%{name: "Posts", externalDocs: %{url: "https://docs.example.com"}}

build_tags(domains, opts \\ [])

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

Builds tags for the OpenAPI specification.

Options

:group_by - Grouping strategy: :resource, :domain, or :custom. Defaults to checking domain configuration, then :resource.
:include_descriptions - Whether to include tag descriptions. Defaults to true.

Examples

iex> AshOaskit.TagBuilder.build_tags([MyApp.Blog], group_by: :resource)
[
  %{name: "Post", description: "Operations on Post resources"},
  %{name: "Comment", description: "Operations on Comment resources"}
]

iex> AshOaskit.TagBuilder.build_tags([MyApp.Blog, MyApp.Shop], group_by: :domain)
[
  %{name: "Blog", description: "Blog domain operations"},
  %{name: "Shop", description: "Shop domain operations"}
]

build_tags_with_docs(domains, opts \\ [])

@spec build_tags_with_docs(
  [module()],
  keyword()
) :: [map()]

Builds tags with external documentation links.

Options

:base_url - Base URL for external documentation.
:group_by - Grouping strategy.

Examples

iex> AshOaskit.TagBuilder.build_tags_with_docs([MyApp.Blog],
...>   base_url: "https://docs.example.com"
...> )
[
  %{
    name: "Post",
    description: "Operations on Post resources",
    externalDocs: %{url: "https://docs.example.com/post"}
  }
]

domain_tag_name(domain)

@spec domain_tag_name(module()) :: String.t()

Extracts the tag name from a domain module.

Examples

iex> AshOaskit.TagBuilder.domain_tag_name(MyApp.Blog)
"Blog"

get_default_grouping(list)

@spec get_default_grouping([module()]) :: atom()

Gets the default grouping strategy for the given domains.

Checks the first domain's configuration for group_by setting. Defaults to :resource.

Examples

iex> AshOaskit.TagBuilder.get_default_grouping([MyApp.Blog])
:resource

merge_tags(generated_tags, custom_tags)

@spec merge_tags([map()], [map()]) :: [map()]

Merges custom tags with generated tags.

Custom tags take precedence over generated tags with the same name.

Examples

iex> generated = [%{name: "Posts"}, %{name: "Comments"}]
...> custom = [%{name: "Posts", description: "Custom description"}]
...> AshOaskit.TagBuilder.merge_tags(generated, custom)
[%{name: "Posts", description: "Custom description"}, %{name: "Comments"}]

operation_tag(route, opts \\ [])

@spec operation_tag(
  map(),
  keyword()
) :: String.t()

Gets the tag name for an operation based on the route.

Options

:group_by - Grouping strategy: :resource or :domain. Defaults to :resource.

Examples

iex> route = %{resource: MyApp.Blog.Post}
...> AshOaskit.TagBuilder.operation_tag(route, group_by: :resource)
"Post"

iex> route = %{resource: MyApp.Blog.Post}
...> AshOaskit.TagBuilder.operation_tag(route, group_by: :domain)
"Blog"

operation_tags(route, opts \\ [])

@spec operation_tags(
  map(),
  keyword()
) :: [String.t()]

Gets tags for an operation (returns as a list for OpenAPI operation tags).

Examples

iex> route = %{resource: MyApp.Blog.Post}
...> AshOaskit.TagBuilder.operation_tags(route)
["Post"]

resource_tag_name(resource)

@spec resource_tag_name(module() | nil) :: String.t() | nil

Extracts the tag name from a resource module.

Returns the last segment of the module name in PascalCase for human-readable tag names.

Examples

iex> AshOaskit.TagBuilder.resource_tag_name(MyApp.Blog.Post)
"Post"