¿Cómo puedo usar overlays de OpenAPI para personalizar la documentación por entorno (dev, staging, producción)? #

Los entornos de desarrollo y staging suelen exponer operaciones experimentales, campos de depuración detallados o límites de velocidad relajados que nunca deberían aparecer en la documentación de producción, y producción puede incluir operaciones que todavía no están disponibles en staging. En lugar de mantener a mano tres documentos OpenAPI casi idénticos, la OpenAPI Overlay Specification permite representar cada entorno como una pequeña diferencia específica respecto a una base compartida.

URL de servidor específicas de cada entorno #

La diferencia más habitual entre entornos es simplemente el bloque servers:

overlay: 1.0.0
info:
  title: Staging Environment Overlay
  version: 1.0.0
actions:
  - target: $.servers
    update: []

Como servers es un arreglo (array), la mayoría de las herramientas de overlays exigen reemplazarlo por completo en lugar de combinar entradas individuales. Un patrón más sencillo y explícito consiste en apuntar a la raíz del documento:

overlay: 1.0.0
info:
  title: Staging Environment Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "https://staging-api.example.com/v1"
          description: "Staging environment"

Exponer operaciones experimentales solo en dev #

overlay: 1.0.0
info:
  title: Development Environment Overlay
  version: 1.0.0
actions:
  - target: $.paths['/experimental/recommendations'].get
    update:
      x-experimental: true
      description: "Experimental — available only in the dev environment. Subject to change without notice."

En los overlays de staging y producción, esa misma ruta simplemente no existiría en el documento base de esos overlays, o se eliminaría de forma explícita si está presente en el origen compartido:

  - target: $.paths['/experimental/recommendations']
    remove: true

Ajustar la documentación de los límites de velocidad #

Los límites de velocidad (rate limits) suelen diferir según el entorno. Un overlay puede actualizar los límites documentados para que reflejen la realidad de cada destino:

  - target: $.paths['/orders'].get
    update:
      x-rate-limit:
        requestsPerMinute: 6000

Los overlays de producción podrían documentar 600, mientras que un overlay de dev documentaría un valor mucho más alto y relajado, de modo que la documentación siga siendo fiel para el entorno con el que el desarrollador esté probando realmente.

Estructurar los archivos de overlay #

overlays/
  env.overlay.dev.yaml
  env.overlay.staging.yaml
  env.overlay.prod.yaml

Integrarlo en una matriz de compilación #

for env in dev staging prod; do
  redocly join openapi.yaml --overlay "overlays/env.overlay.$env.yaml" -o "dist/openapi.$env.yaml"
done

El documento generado para cada entorno puede desplegarse junto al API gateway real de ese entorno, de modo que la documentación que ven los desarrolladores siempre coincida con el comportamiento del entorno al que están apuntando.

Evitar la desviación entre entornos #

Como los overlays son simples archivos YAML bajo control de versiones, las diferencias específicas de cada entorno se hacen visibles en los diffs de las pull requests: quienes revisan pueden ver exactamente qué diferencia a staging de producción sin comparar lado a lado dos archivos de varios miles de líneas.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer los conceptos fundamentales, y ¿Cómo puedo usar overlays de OpenAPI para actualizar las URL de servidor en distintos entornos? para profundizar en el bloque servers en concreto.

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