ExOpenApiUtils.Tag (ex_open_api_utils v0.17.1)

OpenAPI 3.2 Tag struct with support for hierarchical tags.

OpenAPI 3.2 introduces native support for tag hierarchies through:

  • parent - Reference to parent tag for nesting
  • kind - Tag kind (e.g., "navigation" for UI organization)
  • summary - Short label for UI display

Example

alias ExOpenApiUtils.Tag

# Simple tag
%Tag{name: "Users", description: "User management endpoints"}

# Nested tag (OpenAPI 3.2)
%Tag{
  name: "Profile",
  parent: "Users",
  summary: "User Profile",
  description: "User profile management"
}

# Navigation tag (for UI grouping)
%Tag{
  name: "Admin",
  kind: "navigation",
  summary: "Admin Panel"
}

Summary

Types

t()

Functions

navigation(name, opts \\ [])

Creates a navigation tag (kind: "navigation").

nested(name, parent, opts \\ [])

Creates a nested tag with a parent reference.

new(name, opts \\ [])

Creates a new Tag struct from keyword options.

to_open_api_spex(tag)

Converts an ExOpenApiUtils.Tag to an OpenApiSpex.Tag compatible map.

to_open_api_spex_list(tags)

Converts a list of ExOpenApiUtils.Tag structs to OpenApiSpex.Tag structs.

Types

t()

@type t() :: %ExOpenApiUtils.Tag{
  description: String.t() | nil,
  external_docs: map() | nil,
  kind: String.t() | nil,
  name: String.t(),
  parent: String.t() | nil,
  summary: String.t() | nil
}

Functions

nested(name, parent, opts \\ [])

@spec nested(String.t(), String.t(), keyword()) :: t()

Creates a nested tag with a parent reference.

Example

Tag.nested("Profile", "Users", summary: "User Profile")

new(name, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Creates a new Tag struct from keyword options.

Options

  • :name - (required) Tag name
  • :description - Tag description
  • :parent - Parent tag name for nesting (OpenAPI 3.2)
  • :kind - Tag kind, e.g., "navigation" (OpenAPI 3.2)
  • :summary - Short summary for UI display (OpenAPI 3.2)
  • :external_docs - Map with :url and optional :description

Example

Tag.new("Users",
  description: "User management",
  parent: "Admin",
  summary: "Users"
)

to_open_api_spex(tag)

@spec to_open_api_spex(t()) :: OpenApiSpex.Tag.t()

Converts an ExOpenApiUtils.Tag to an OpenApiSpex.Tag compatible map.

OpenAPI 3.2 fields (parent, kind, summary) are serialized directly as they are now part of the standard specification.

Example

tag = %Tag{name: "Users", parent: "Admin", summary: "User Management"}
Tag.to_open_api_spex(tag)
# => %OpenApiSpex.Tag{
#   name: "Users",
#   extensions: %{
#     "parent" => "Admin",
#     "summary" => "User Management"
#   }
# }

Note: Until OpenApiSpex natively supports 3.2 fields, we use extensions. The fields will serialize correctly in the final JSON/YAML output.

to_open_api_spex_list(tags)

@spec to_open_api_spex_list([t()]) :: [OpenApiSpex.Tag.t()]

Converts a list of ExOpenApiUtils.Tag structs to OpenApiSpex.Tag structs.