How can I use OpenAPI overlays to add custom tags and categorization to endpoints?

How can I use OpenAPI overlays to add custom tags and categorization to endpoints? #

Tags are what drive the sidebar navigation and grouping in most OpenAPI documentation renderers, including Redoc and Swagger UI. As an API grows organically, tagging often becomes inconsistent — some operations get no tag at all, others get overly specific one-off tags. Reorganizing this by hand across a large spec is tedious and risks introducing typos. The OpenAPI Overlay Specification lets you apply a clean tagging taxonomy as a separate, reviewable layer.

Adding Tags to Untagged Operations #

overlay: 1.0.0
info:
  title: Documentation Tagging Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].get
    update:
      tags: ["Orders"]
  - target: $.paths['/orders'].post
    update:
      tags: ["Orders"]
  - target: $.paths['/orders/{id}/cancel'].post
    update:
      tags: ["Orders"]

Defining Tag Metadata and Ordering #

The top-level tags array controls the display order and descriptions shown in generated docs. This too can be introduced entirely through an overlay:

  - target: $
    update:
      tags:
        - name: "Orders"
          description: "Create and manage customer orders."
        - name: "Payments"
          description: "Process and refund payments."
        - name: "Webhooks"
          description: "Subscribe to asynchronous event notifications."

Re-Tagging Without Breaking Existing Groupings #

If an operation currently has an inconsistent tag like order-mgmt that needs to become Orders, target it directly and replace the array:

  - target: $.paths['/orders/{id}'].patch
    update:
      tags: ["Orders"]

Because update performs a merge and arrays are typically replaced wholesale rather than concatenated, the new tags array fully overrides the old one for that operation — verify this behavior against your specific overlay tool, since merge semantics for arrays can vary between implementations.

Introducing Nested Tag Groups #

Some renderers, including Redoc, support an x-tagGroups extension for grouping tags into higher-level categories in the sidebar. This is a great candidate for an overlay since it’s purely a documentation-presentation concern:

  - target: $
    update:
      x-tagGroups:
        - name: "Core Resources"
          tags: ["Orders", "Payments"]
        - name: "Integrations"
          tags: ["Webhooks"]

Auditing Tag Consistency Before Applying #

Before writing the overlay, it helps to generate a quick report of every operation’s current tags to spot inconsistencies:

yq '.paths[].*.tags' openapi.yaml | sort | uniq -c | sort -rn

This reveals which tags are used once (likely typos or one-offs) versus which represent a genuine, recurring category worth keeping.

Applying the Overlay #

redocly join openapi.yaml --overlay tagging-overlay.yaml -o dist/openapi.yaml
redocly build-docs dist/openapi.yaml -o dist/docs/index.html

See What is the OpenAPI Overlay Specification? for the general model, and How can I use OpenAPI overlays to generate audience-specific API documentation? for how tagging fits into a broader multi-output documentation strategy.

Last updated on July 16, 2026.