¿Cómo usar los overlays de OpenAPI? #

La OpenAPI Overlay Specification ofrece una forma estructurada de aplicar cambios a un documento OpenAPI sin tocar el archivo original. En lugar de mantener varias copias divergentes del mismo documento para distintos públicos o entornos, mantienes una única descripción OpenAPI canónica y uno o más archivos de overlay que describen las diferencias. Esta guía recorre todas las opciones disponibles en un documento de overlay y muestra un ejemplo funcional de cada una.

Para conocer el contexto de por qué existen los overlays y qué problemas resuelven, consulta ¿Qué es la OpenAPI Overlay Specification?.

Los componentes básicos de un documento de overlay #

Un documento de overlay es un archivo YAML o JSON con los siguientes campos de nivel superior:

Cada entrada de actions admite:

En cada acción solo se debe establecer una de las opciones update, remove o copy; si están presentes tanto update como copy, se ignora update.

Paso 1: declara el overlay y a qué apunta #

Empieza con la versión overlay y el bloque info, y, si quieres, indica el documento base con extends:

overlay: 1.1.0
info:
  title: Public API Overlay
  version: 1.0.0
  description: Strips internal-only endpoints and rewrites the public description.
extends: ./api.yaml
actions: []

Paso 2: selecciona nodos con JSONPath #

Cada acción necesita una expresión target para seleccionar el nodo o nodos a los que se aplica. Algunos patrones habituales:

$.info                                    # the info object
$.paths.*                                 # every path item
$.paths.*.*.responses                     # every response object, across all operations
$.components.schemas.User                 # the User schema component
$.paths['/orders'].post.summary           # the summary of the POST /orders operation
$.paths.*.get.tags[?@ == 'dummy']         # a specific tag value inside an array

Como las expresiones de target deben ser conformes con RFC 9535, algunas expresiones de filtro pueden necesitar paréntesis adicionales según la implementación de JSONPath de tus herramientas, por ejemplo parameters[?(@.name=='filter')] en lugar de parameters[?@.name=='filter'].

Paso 3: elige una acción #

update: añade o reemplaza valores #

update realiza una fusión en profundidad (deep merge) en el nodo coincidente, de forma similar a JSON Merge Patch (RFC 7396). Las claves que no se mencionan se conservan.

overlay: 1.1.0
info:
  title: Update info and one operation
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "This is the public-facing version of our API."
  - target: $.paths['/users/{id}'].get
    update:
      summary: "Retrieve a user by their unique identifier"
      x-internal-note: "Cached for 60 seconds"

Desde la versión 1.1.0, update también funciona directamente con nodos de valor primitivo:

- target: $.paths['/foo'].get.description
  update: This is the new description

remove: elimina nodos #

remove elimina por completo el nodo coincidente. Se utiliza con frecuencia para quitar endpoints internos o administrativos antes de publicar la documentación pública:

overlay: 1.1.0
info:
  title: Remove an internal endpoint
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin']
    remove: true

Desde la versión 1.1.0, remove también funciona con una única entrada primitiva dentro de un arreglo, como una etiqueta entre varias:

- target: $.paths.*.get.tags[?@ == 'dummy']
  remove: true

copy: duplica o mueve nodos #

copy, introducida en la versión 1.1.0, fusiona un valor seleccionado desde otra parte del mismo documento en lugar de un valor literal escrito en el overlay. Esto es lo que permite renombrar o mover un nodo usando únicamente overlays:

overlay: 1.1.0
info:
  title: Rename the items path
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "/new-items": {} }
  - target: '$.paths["/new-items"]'
    copy: '$.paths["/items"]'
  - target: '$.paths["/items"]'
    remove: true
    description: 'moves (renames) the "items" path item to "new-items"'

Esta secuencia sigue la receta general para cualquier movimiento o cambio de nombre: asegúrate de que el destino exista, copia en él el origen y, después, elimina el origen. Las acciones se ejecutan en el orden en que aparecen, por lo que la acción update que crea /new-items debe ir antes de la acción copy que la rellena.

Cómo reunirlo todo #

Un único archivo de overlay puede combinar update, remove y copy libremente, ya que las acciones se aplican simplemente en secuencia sobre el documento base:

overlay: 1.1.0
info:
  title: Public documentation overlay
  version: 1.2.0
  description: Prepares the internal API description for external publication.
extends: ./internal-api.yaml
actions:
  - target: $.info
    update:
      description: "This is the public-facing version of our API."
  - target: $.paths['/internal/metrics']
    remove: true
  - target: '$.paths'
    update: { "/orders-v2": {} }
  - target: '$.paths["/orders-v2"]'
    copy: '$.paths["/orders"]'
  - target: $.paths['/orders-v2'].post.summary
    update: "Create an order (v2 endpoint)"

Aplicar un overlay #

Los overlays suelen aplicarse con una herramienta de línea de comandos (CLI) como parte de un paso de compilación o de CI/CD, en lugar de hacerlo a mano. Entre las herramientas con compatibilidad documentada se encuentran:

• Redocly CLI: una de las primeras herramientas en incluir el comando overlay.
• Bump.sh CLI y Speakeasy CLI: compatibilidad con overlays dentro de flujos de trabajo más amplios de documentación y SDK.
• overlays-js y overlay-jvm: bibliotecas para aplicar overlays de forma programática desde JavaScript o la JVM.
• apigee-go-gen, openapi-format y oas-patch: conjuntos de herramientas CLI de transformación que incluyen compatibilidad con overlays.

Consulta el repositorio de la Overlay Specification de la OAI para ver la lista actual de herramientas y la versión de la Overlay Specification que admite cada una, ya que copy, update/remove con valores primitivos y el requisito de RFC 9535 solo se añadieron en la versión 1.1.0.

Lecturas relacionadas #

• ¿Qué es la OpenAPI Overlay Specification?
• ¿Cómo puedo usar overlays de OpenAPI para eliminar endpoints internos antes de publicar la documentación?
• ¿Cómo puedo usar overlays de OpenAPI para añadir ejemplos a un documento OpenAPI existente?
• ¿Cómo puedo usar overlays de OpenAPI para copiar o mover elementos en un documento OpenAPI?
• ¿Cómo puedo usar overlays de OpenAPI para probar y validar los cambios antes de publicarlos?

Última actualización: 7 de agosto de 2026.