¿Cómo puedo usar overlays de OpenAPI para automatizar cambios en un pipeline de CI/CD? #

Aplicar un overlay manualmente en el portátil de un desarrollador sirve para un experimento rápido, pero el verdadero valor de la OpenAPI Overlay Specification está en automatizarlo: cada vez que cambia el documento OpenAPI canónico, todos los resultados derivados (documentación pública, SDKs, especificaciones para socios) deben regenerarse de forma coherente, sin que nadie tenga que acordarse de ejecutar un comando a mano.

La forma típica de un pipeline #

1. Analizar con un linter y validar el documento OpenAPI base.
2. Aplicar uno o más overlays para producir los documentos derivados.
3. Validar cada documento derivado de forma independiente.
4. Publicar o distribuir cada documento derivado a su destino (portal de documentación, generador de SDK, entrega a socios).

Ejemplo de workflow de GitHub Actions #

name: openapi-overlays

on:
  push:
    branches: [main]
    paths:
      - 'openapi.yaml'
      - 'overlays/**'

jobs:
  apply-overlays:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      - name: Lint base document
        run: redocly lint openapi.yaml

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

      - name: Apply partner overlay
        run: redocly join openapi.yaml --overlay overlays/partner.yaml -o dist/openapi.partner.yaml

      - name: Lint derived documents
        run: |
          redocly lint dist/openapi.public.yaml
          redocly lint dist/openapi.partner.yaml

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: openapi-derived-documents
          path: dist/

Hacer fallar la compilación ante desviaciones inesperadas #

Una salvaguarda útil es hacer que el pipeline falle si, al aplicar un overlay, se obtiene una diferencia vacía respecto a la ejecución anterior cuando se esperaba un cambio real en el documento base. Esto permite detectar los casos en los que un destino JSONPath ya no coincide con nada porque la estructura subyacente cambió (por ejemplo, se renombró una ruta y el target del overlay dejó de coincidir sin avisar).

redocly join openapi.yaml --overlay overlays/public.yaml -o /tmp/new.yaml
diff dist/openapi.public.yaml /tmp/new.yaml || echo "Overlay output changed — review before merging"

Condicionar las fusiones a la validación de overlays #

Añade el paso de aplicación de overlays como comprobación obligatoria en las pull requests, y no solo en main, de modo que un overlay roto (JSONPath no válido, YAML mal formado) se detecte antes de la fusión y no después del despliegue:

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'overlays/**'

Versionar los resultados derivados #

Etiqueta el nombre de archivo o la ruta de cada documento derivado con el SHA del commit o con la versión de la publicación, de modo que los resultados históricos sigan disponibles para auditorías:

redocly join openapi.yaml --overlay overlays/public.yaml -o "dist/openapi.public.${GITHUB_SHA}.yaml"

Notificar a los consumidores posteriores #

Si los socios o los equipos de SDK consumen directamente el resultado derivado, activa un pipeline posterior o un webhook una vez publicado el nuevo documento derivado, en lugar de confiar en que consulten los cambios manualmente.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo subyacente, y ¿Cómo puedo usar overlays de OpenAPI para probar y validar cambios antes de publicarlos? para ver estrategias de validación más profundas que puedes ejecutar dentro de este pipeline.

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