¿Cómo puedo usar overlays de OpenAPI para generar documentación de API específica para cada audiencia? #

Una sola API rara vez tiene una única audiencia. Los ingenieros internos necesitan un detalle técnico exhaustivo, los socios necesitan un subconjunto seleccionado con contexto de negocio y el público general necesita una vista simplificada y amigable. Mantener tres (o más) copias de un documento OpenAPI editadas a mano no es sostenible. La OpenAPI Overlay Specification permite expresar la vista de cada audiencia como su propio overlay, que se aplica bajo demanda sobre la misma fuente canónica.

Diseñar el documento canónico #

El documento canónico debe contener la unión de todo lo que cualquier audiencia pueda necesitar: descripciones técnicas completas, notas internas como extensiones x- y todos los endpoints, incluidos los de uso exclusivamente interno. Los overlays específicos de cada audiencia después restan o transforman, pero nunca añaden capacidades completamente nuevas.

paths:
  /internal/admin/audit-log:
    get:
      x-internal: true
      summary: Retrieve the raw audit log
  /orders:
    get:
      summary: List orders
      x-internal-note: "Backed by the orders-service read replica."

Overlay para ingenieros internos #

El overlay interno suele hacer muy poco, quizá solo añadir enlaces a runbooks:

overlay: 1.0.0
info:
  title: Internal Engineering Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].get
    update:
      description: "See the runbook at https://wiki.internal/orders-service for on-call guidance."

Overlay para socios externos #

El overlay para socios elimina los endpoints y las notas internas, y puede reescribir los resúmenes para que sean más cercanos al lenguaje de negocio:

overlay: 1.0.0
info:
  title: Partner Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/audit-log']
    remove: true
  - target: $.paths['/orders'].get
    update:
      summary: "Retrieve your order history"
      x-internal-note: null

Overlay para el portal público #

El overlay público suele ser el más agresivo: elimina todo lo que no esté pensado para una audiencia general y, posiblemente, renombra los operationIds para que resulten más amigables para el consumidor en los ejemplos de SDK generados:

overlay: 1.0.0
info:
  title: Public Portal Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/audit-log']
    remove: true
  - target: $.info
    update:
      description: "A simple, developer-friendly API for managing orders."

Compilar las tres versiones en un pipeline #

redocly join openapi.yaml --overlay overlays/internal.yaml   -o dist/openapi.internal.yaml
redocly join openapi.yaml --overlay overlays/partner.yaml    -o dist/openapi.partner.yaml
redocly join openapi.yaml --overlay overlays/public.yaml     -o dist/openapi.public.yaml

Cada resultado puede publicarse después en su propio portal de documentación, creado con herramientas como Redoc o Swagger UI, todos a partir de una única especificación.

Mantener los overlays fáciles de revisar #

Como cada overlay específico de una audiencia es pequeño y declarativo, quienes revisan el código pueden ver rápidamente qué difiere para cada audiencia sin leer un documento completo duplicado: revisar un diff de un overlay de 20 líneas es mucho más sencillo que revisar el de una especificación de 2000 líneas.

Lecturas relacionadas #

Para conocer el mecanismo subyacente, consulta ¿Qué es la OpenAPI Overlay Specification?. Para ver una versión más acotada de este patrón centrada únicamente en socios externos, consulta ¿Cómo puedo usar overlays de OpenAPI para crear subconjuntos de API específicos para socios?.

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