¿Cómo puedo usar overlays de OpenAPI para eliminar endpoints internos antes de publicar la documentación? #

La mayoría de las API reales exponen una mezcla de operaciones públicas y endpoints de uso exclusivamente interno para administración, depuración o herramientas internas. Cuando llega el momento de publicar la documentación para desarrolladores externos o socios, esos endpoints internos no deben aparecer. En lugar de mantener una segunda copia del documento OpenAPI depurada a mano, la OpenAPI Overlay Specification te permite eliminar esas rutas de forma declarativa, como un paso de transformación independiente y reutilizable.

Por qué es importante #

Eliminar rutas manualmente de una copia de tu especificación genera divergencias: cada vez que cambia el documento canónico, alguien tiene que acordarse de volver a aplicar las mismas ediciones manuales a la copia «pública». Esto es propenso a errores y no escala. Un overlay expresa la eliminación como datos, de modo que puede volver a aplicarse automáticamente cada vez que se regenera el documento base.

Identificar los endpoints internos #

Una convención habitual es etiquetar las operaciones internas, ya sea con el arreglo (array) tags o con una extensión de proveedor como x-internal: true:

paths:
  /internal/admin/reindex:
    post:
      tags: [internal]
      x-internal: true
      summary: Trigger a manual search reindex
  /users:
    get:
      tags: [public]
      summary: List users

Contar con un marcador coherente facilita mucho apuntar a estas operaciones desde un overlay.

Escribir el overlay #

Con JSONPath puedes apuntar directamente a rutas concretas por su clave, o usar expresiones con comodines asociadas a etiquetas si tus herramientas admiten selección condicional. El enfoque más sencillo y fiable es apuntar a las claves exactas de las rutas:

overlay: 1.0.0
info:
  title: Public Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/reindex']
    remove: true
  - target: $.paths['/internal/metrics']
    remove: true
  - target: $.paths['/internal/feature-flags']
    remove: true

Cada acción remove: true elimina el elemento de ruta completo, incluidos todos los métodos HTTP definidos bajo él.

Eliminar operaciones individuales en lugar de rutas completas #

A veces solo un método de una ruta es interno, mientras que los demás son públicos. Apunta a la operación concreta en lugar de al elemento de ruta completo:

actions:
  - target: $.paths['/orders'].delete
    remove: true

Así, GET /orders y POST /orders siguen visibles, mientras que la operación interna DELETE /orders queda oculta.

Limpiar los componentes huérfanos #

Al eliminar rutas pueden quedar esquemas huérfanos en components.schemas que ya no se referencian en ningún lugar del documento. Los overlays no podan automáticamente los componentes sin uso; esto suele resolverse con un paso posterior de linting o de empaquetado (bundling). Herramientas como Redocly CLI pueden señalar los componentes sin uso una vez aplicado el overlay, por lo que es buena práctica ejecutar un paso de bundle y lint inmediatamente después de aplicarlo.

Aplicar el overlay #

Con Redocly CLI, aplicar un overlay es un único comando:

redocly join openapi.yaml --overlay public-overlay.yaml -o public-openapi.yaml

El resultado es un documento nuevo sin ningún endpoint interno, listo para publicarse en un portal de documentación, sin haber modificado nunca el archivo de origen.

Automatizarlo en tu pipeline #

Como el overlay es simplemente un archivo, debe estar bajo control de versiones junto con tu documento OpenAPI. Un trabajo típico de CI/CD podría:

1. Validar el documento OpenAPI base.
2. Aplicar el overlay «público» para generar una copia censurada (redacted).
3. Publicar la copia censurada en el portal de documentación externo.
4. Publicar el documento base intacto en un portal exclusivamente interno.

Así se mantiene una única fuente de verdad y se generan automáticamente dos salidas adaptadas en cada merge.

Lecturas relacionadas #

Para más información sobre cómo funcionan los overlays en general, consulta ¿Qué es la OpenAPI Overlay Specification?. Si necesitas censurar campos concretos en lugar de endpoints completos, consulta ¿Cómo puedo usar overlays de OpenAPI para censurar (redact) campos sensibles de un documento OpenAPI?.

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