OpenAPI tag

As explained in The Design of Web APIs, Second Edition

An OpenAPI tag is metadata that groups related API operations for organization and documentation.

An OpenAPI tag is metadata attached to operations to group related API capabilities. Renderers use tag names for navigation, turning a flat operation list into an overview of concepts and use cases. section 19.2.2

Choose tags around concepts that cross resource boundaries or around user goals. A root-level tags list controls group order; without it, tools generally order tags as defined. Tags can clarify an API, but they cannot reorder operations to show a use-case sequence. section 19.2.2

Banking API transfer overview

Assign operations involving transfers, sources, and destinations to the shared “Concept - Transfer” tag. Add a “Modified by v1.2” tag alongside the default “All” tag when highlighting changed operations. For a use-case tag, add a Markdown description or externalDocs link when readers need the related workflow; otherwise, a Postman Collection may provide more useful request examples and testing. section 19.2.2 section 15.7.3 section 19.2.3

Figure 19.4 Group operations by adding tags. Sort groups by adding the root-level tags list. Operations can’t be reordered in groups.

Use the grouping illustration to compare operation tags with root-level ordering and see the limitation on ordering operations within a group. section 19.2.2

When code generation matters, tags may also group generated operations into classes, modules, or files. Select or ignore tags deliberately, and pair them with unique operationId values when generated function names need to be predictable. section 19.5.2

How The Design of Web APIs, Second Edition covers it

How deep it goes

Defines operation and root-level tag usage, ordering, descriptions, and workflow limits, but stops short of prescribing a universal taxonomy.

Examples

Uses Banking API transfer tags, version-change tags, root-level ordering, Markdown descriptions, and generated code groups.

What it assumes

Assumes an OpenAPI document containing operations and distinguishes operation-level tags from the root-level tags list.

What you can do after

Apply tags to make rendered OpenAPI navigation clearer and to influence organization in code-generation outputs.

How it connects

Connects OpenAPI operation objects with API Capabilities Canvas, externalDocs, Postman Collection, and code generation.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Related concepts

• OpenAPI specificationused by · The OpenAPI Specification is a standard, machine-readable format for describing HTTP APIs, including their operations, inputs, outputs, data structures, and security requirements.
• operationconfigures · An operation is an action or computation performed by or through a system, object, or interface, often producing a result or effect.
• code generationuses · Code generation is the production of program code by transforming inputs such as specifications, models, templates, or existing representations.
• endpointconfigures · An endpoint is a network-accessible address or interface through which a service exposes a resource or operation and handles requests and responses.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.