¿Cómo puedo usar overlays de OpenAPI para añadir etiquetas y categorización personalizadas a los endpoints? #

Las etiquetas son las que determinan la navegación de la barra lateral y la agrupación en la mayoría de los generadores de documentación de OpenAPI, entre ellos Redoc y Swagger UI. A medida que una API crece de forma orgánica, el etiquetado suele volverse incoherente: algunas operaciones no reciben ninguna etiqueta y otras reciben etiquetas demasiado específicas, creadas para un único caso. Reorganizar todo esto a mano en una especificación grande es tedioso y puede introducir errores tipográficos. La OpenAPI Overlay Specification te permite aplicar una taxonomía de etiquetas limpia como una capa independiente y revisable.

Añadir etiquetas a operaciones sin etiquetar #

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"]

Definir los metadatos y el orden de las etiquetas #

El arreglo (array) tags de nivel superior controla el orden de presentación y las descripciones que se muestran en la documentación generada. Esto también puede introducirse por completo mediante un 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."

Reasignar etiquetas sin romper las agrupaciones existentes #

Si una operación tiene actualmente una etiqueta incoherente como order-mgmt que debe pasar a ser Orders, apunta directamente a ella y reemplaza el arreglo:

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

Dado que update realiza una combinación (merge) y que los arreglos suelen reemplazarse por completo en lugar de concatenarse, el nuevo arreglo tags sustituye totalmente al anterior para esa operación. Verifica este comportamiento con tu herramienta de overlays concreta, ya que la semántica de combinación de arreglos puede variar entre implementaciones.

Introducir grupos de etiquetas anidados #

Algunos generadores, como Redoc, admiten la extensión x-tagGroups para agrupar etiquetas en categorías de nivel superior en la barra lateral. Es un buen candidato para un overlay, ya que se trata exclusivamente de un aspecto de presentación de la documentación:

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

Auditar la coherencia de las etiquetas antes de aplicar el overlay #

Antes de escribir el overlay, conviene generar un informe rápido con las etiquetas actuales de cada operación para detectar incoherencias:

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

Esto revela qué etiquetas se usan una sola vez (probablemente errores tipográficos o casos aislados) y cuáles representan una categoría genuina y recurrente que vale la pena conservar.

Aplicar el overlay #

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

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo general, y ¿Cómo puedo usar overlays de OpenAPI para generar documentación de API específica para cada audiencia? para ver cómo encaja el etiquetado en una estrategia más amplia de documentación con múltiples salidas.

Última actualización: 16 de julio de 2026.