¿Cómo puedo usar overlays de OpenAPI para probar y validar cambios antes de publicar? #

Un overlay que apunta a una expresión JSONPath que ya no coincide con nada falla en silencio en la mayoría de las herramientas: la acción simplemente se omite en lugar de generar un error. Por eso, validar el resultado de aplicar un overlay es tan importante como validar el propio documento base de la OpenAPI Overlay Specification. Un flujo de validación sólido detecta destinos rotos, regresiones estructurales y efectos secundarios no deseados antes de que lleguen a un portal de documentación o a una compilación de SDK.

Capa 1: Validar el documento base #

Antes de aplicar cualquier overlay, confirma que el documento base es en sí mismo un OpenAPI válido:

redocly lint openapi.yaml

Capa 2: Validar el propio archivo del overlay #

Confirma que el archivo del overlay cumple el esquema de la propia Overlay Specification (versión, info y actions bien formadas):

redocly lint overlays/public.yaml --format=overlay

No todas las herramientas permiten aplicar linting directamente a los archivos de overlay; consulta la documentación de tu herramienta para saber si admite la validación del esquema de overlay.

Capa 3: Validar el resultado combinado #

Después de aplicar el overlay, aplica linting al documento resultante exactamente como lo harías con cualquier otro archivo OpenAPI:

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

Capa 4: Comprobar que los destinos esperados coincidieron realmente #

Como un JSONPath mal escrito no hace nada en silencio, escribe una prueba explícita que confirme que los cambios conocidos se aplicaron de verdad:

const yaml = require('js-yaml');
const fs = require('node:fs');

const merged = yaml.load(fs.readFileSync('dist/openapi.public.yaml', 'utf8'));

if (merged.paths['/internal/admin']) {
  throw new Error('Overlay failed to remove /internal/admin — check the JSONPath target');
}

if (!merged.info.description.includes('public-facing')) {
  throw new Error('Overlay failed to update info.description');
}

Ejecutar este tipo de comprobaciones en CI convierte un fallo silencioso del overlay en un fallo de compilación inmediato y evidente.

Capa 5: Comparar con la compilación anterior #

Comparar el documento recién generado con la última versión buena conocida pone de relieve cambios no deseados que un revisor podría pasar por alto en una diferencia (diff) extensa:

redocly diff dist/openapi.public.previous.yaml dist/openapi.public.yaml

Capa 6: Pruebas de instantáneas de la documentación generada #

Para los equipos que generan documentación HTML a partir de la especificación combinada, una prueba de instantáneas visuales (con una herramienta como Percy o capturas de pantalla de Playwright) puede detectar regresiones de renderizado introducidas indirectamente por un cambio en un overlay; por ejemplo, un ejemplo ausente que deja una página de documentación con un aspecto vacío.

Reunirlo todo en CI #

- name: Validate base
  run: redocly lint openapi.yaml

- name: Apply and validate overlay
  run: |
    redocly join openapi.yaml --overlay overlays/public.yaml -o dist/openapi.public.yaml
    redocly lint dist/openapi.public.yaml

- name: Assert overlay effects
  run: node scripts/assert-overlay-effects.js

- name: Diff against previous build
  run: redocly diff dist/openapi.public.previous.yaml dist/openapi.public.yaml || true

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo subyacente, y ¿Cómo puedo usar overlays de OpenAPI para automatizar cambios en un pipeline de CI/CD? para ver cómo encaja este flujo de validación en un pipeline automatizado más amplio.

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