Una PR modifica openapi.yaml. CI pasa, la especificación es válida, el linter no se queja y dos revisores aprueban. Tres días después, una app móvil empieza a fallar por punteros nulos porque un campo de respuesta desapareció. Nadie lo eliminó intencionalmente: alguien renombró una propiedad durante una refactorización y la revisión no lo detectó.

Prueba Apidog hoy

Ese es el hueco que un validador de OpenAPI no cubre. Una especificación puede estar bien formada y aun así romper clientes existentes. Para detectarlo necesitas comparar la nueva especificación contra la versión que reemplaza y responder una pregunta concreta: ¿este cambio rompería a un cliente que funcionaba ayer?

Eso es un diff de OpenAPI. Ejecutarlo como una puerta de merge en CI es una de las comprobaciones con mejor retorno que puedes añadir a un repositorio de API.

Qué compara realmente un diff de OpenAPI

Un diff de OpenAPI compara dos especificaciones:

• Base: la especificación actual, normalmente la de la rama objetivo.
• Head: la especificación propuesta por la PR.

A diferencia de git diff, una herramienta de diff para OpenAPI entiende la estructura del contrato: rutas, métodos, parámetros, esquemas, respuestas, tipos, campos requeridos y enums.

Cambios normalmente seguros:

• Añadir un parámetro opcional.
• Añadir un campo de respuesta.
• Añadir un endpoint nuevo.
• Añadir un valor de enum en un cuerpo de solicitud.

Cambios incompatibles:

• Eliminar un campo de respuesta.
• Renombrar una propiedad.
• Convertir un parámetro opcional en requerido.
• Cambiar un tipo de forma restrictiva, por ejemplo de string a integer.
• Eliminar un valor de enum que un cliente podría enviar.
• Eliminar un endpoint o método HTTP.

El objetivo no es ver líneas modificadas, sino clasificar cambios de contrato. Un diff textual puede ocultar un cambio en required entre decenas de líneas reformateadas. Un diff estructural lo reporta como ruptura y muestra dónde ocurre.

Si quieres profundizar en las reglas de compatibilidad, la guía sobre cómo versionar y deprecar APIs a escala explica cuándo un cambio debe considerarse rompedor.

oasdiff: la opción open source práctica

oasdiff es una herramienta open source escrita en Go. Es rápida, se distribuye como binario único y está diseñada para detectar cambios incompatibles en especificaciones OpenAPI 3.0 y 3.1.

Los subcomandos más útiles son:

• diff: muestra todas las diferencias.
• breaking: muestra solo cambios incompatibles.
• changelog: genera una lista legible de cambios.

Para usarlo como puerta de merge, ejecuta breaking:

oasdiff breaking base-openapi.yaml head-openapi.yaml --fail-on ERR

Donde:

• base-openapi.yaml es la especificación de la rama objetivo.
• head-openapi.yaml es la especificación de la PR.
• --fail-on ERR hace que el comando termine con código distinto de cero si encuentra una ruptura grave.

Ese código de salida es lo que CI interpreta como fallo.

También puedes ser más estricto:

oasdiff breaking base-openapi.yaml head-openapi.yaml --fail-on WARN

ERR bloquea rupturas claras. WARN también bloquea cambios que podrían romper algunos clientes según cómo estén implementados.

Para generar un resumen legible:

oasdiff changelog base-openapi.yaml head-openapi.yaml

oasdiff también puede emitir resultados en HTML, JSON, YAML y Markdown, lo que facilita adjuntar el resultado a una PR o publicarlo como artefacto de CI.

openapi-diff: alternativa para equipos JVM

Si tu stack ya usa Java, OpenAPITools/openapi-diff es otra opción sólida. Compara especificaciones OpenAPI 3.x y puede generar salida en HTML, Markdown, AsciiDoc, JSON o consola.

Uso básico:

openapi-diff old-openapi.yaml new-openapi.yaml --fail-on-incompatible

El flag --fail-on-incompatible hace que el comando falle solo cuando detecta cambios incompatibles.

También tienes opciones más estrictas:

openapi-diff old-openapi.yaml new-openapi.yaml --fail-on-changed

Y un modo útil para scripts:

openapi-diff old-openapi.yaml new-openapi.yaml --state

Este último imprime solo uno de estos estados:

no_changes
compatible
incompatible

openapi-diff destaca por sus reportes HTML y Markdown. La desventaja es que requiere JVM y suele ser más pesado que un binario de Go. Si ya tienes Java en tu pipeline, es una buena opción. Si no, oasdiff suele ser más simple de incorporar.

Añadir el diff a GitHub Actions

Un diff manual no basta. Debe ejecutarse automáticamente en cada PR que modifique la especificación.

Ejemplo con oasdiff y GitHub Actions:

name: openapi-diff

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  breaking-changes:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get base spec
        run: git show origin/${{ github.base_ref }}:openapi.yaml > base-openapi.yaml

      - name: Install oasdiff
        run: |
          curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

      - name: Diff for breaking changes
        run: oasdiff breaking base-openapi.yaml openapi.yaml --fail-on ERR

Puntos importantes:

• fetch-depth: 0 permite acceder a la rama base.
• git show origin/${{ github.base_ref }}:openapi.yaml extrae la especificación actual de la rama objetivo.
• paths evita ejecutar el job cuando no cambia openapi.yaml.
• oasdiff breaking ... --fail-on ERR bloquea la PR si hay rupturas.

Con esto, el autor ve el cambio incompatible mientras la PR aún está en revisión.

No todos los cambios incompatibles son errores. A veces estás publicando una versión mayor deliberadamente. En ese caso, conviene permitir excepciones explícitas: una etiqueta de PR, un incremento en info.version o un workflow aprobado. La guía de estrategia de versionado de API ayuda a decidir cuándo una ruptura justifica una nueva versión.

Lo que un diff no puede detectar

Un diff compara dos archivos. Puede decirte si la nueva especificación es compatible con la anterior, pero no puede verificar si tu servicio real cumple esa especificación.

Ejemplo:

• La especificación dice que la respuesta incluye created_at.
• La implementación dejó de devolverlo hace tres sprints.
• Ambas versiones de openapi.yaml siguen diciendo que created_at existe.

El diff pasa porque los archivos coinciden entre sí. Pero el contrato y la implementación ya no coinciden.

Para cerrar ese hueco necesitas pruebas de contrato: generar o mantener pruebas desde la especificación, ejecutarlas contra la API real y validar que las respuestas coinciden con lo documentado.

La prueba de contrato cubre exactamente ese caso: detectar desviaciones entre lo que la API promete y lo que realmente devuelve.

Complementar el diff con Apidog y Apidog CLI

Apidog encaja como complemento del diff, no como reemplazo.

El flujo práctico es:

1. Importas o sincronizas tu especificación OpenAPI en Apidog.
2. Generas escenarios de prueba desde la especificación.
3. Ejecutas esos escenarios contra un entorno real.
4. CI falla si la respuesta real no cumple el contrato.

Apidog puede generar colecciones de prueba desde especificaciones OpenAPI, incluyendo aserciones basadas en esquemas, tipos, campos requeridos y códigos de estado.

También puedes descargar Apidog e importar una especificación existente para probar el flujo. Si todavía estás definiendo cómo versionar la especificación, el tutorial sobre control de versiones de una especificación OpenAPI con Git complementa bien este enfoque.

La CLI de Apidog permite ejecutar esos escenarios en CI.

Instalación:

npm install -g apidog-cli

Ejecución de un escenario:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenarioId> \
  -e <environmentId> \
  -r junit,cli \
  --out-dir ./apidog-reports

Dónde:

• --access-token autentica la ejecución. Debe guardarse como secreto de CI.
• -t selecciona el escenario.
• -e selecciona el entorno.
• -r junit,cli genera salida JUnit para CI y salida legible en consola.
• --out-dir define dónde guardar los reportes.

No necesitas adivinar los IDs. Puedes copiar el comando completo desde la pestaña CI/CD del escenario en Apidog. Para ver todas las opciones, consulta la guía completa de la CLI o ejecuta:

apidog run --help

Si una aserción falla, apidog run termina con código distinto de cero. CI marca el job como fallido y bloquea la PR.

Pipeline completo antes del merge

El pipeline ideal ejecuta dos comprobaciones separadas:

1. Diff de OpenAPI: detecta cambios incompatibles entre especificaciones.
2. Pruebas de contrato: validan que la API real cumple la especificación.

Ejemplo completo en GitHub Actions:

jobs:
  breaking-changes:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - run: git show origin/${{ github.base_ref }}:openapi.yaml > base-openapi.yaml

      - run: curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

      - run: oasdiff breaking base-openapi.yaml openapi.yaml --fail-on ERR

  contract-conformance:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm install -g apidog-cli

      - name: Run contract tests
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

Los dos jobs pueden ejecutarse en paralelo:

• breaking-changes solo compara archivos y suele terminar rápido.
• contract-conformance necesita un entorno real, normalmente staging.

El if: always() en la subida del reporte asegura que puedas revisar los resultados incluso cuando las pruebas fallan.

Si cualquiera de los dos jobs falla, la PR se bloquea.

Para profundizar en la ejecución de la CLI en pipelines reales, revisa la guía de Apidog CLI con GitHub Actions y el tutorial de pipelines CI/CD.

Resumen operativo

Para evitar rupturas accidentales de contrato:

1. Mantén la especificación OpenAPI versionada en Git.
2. Ejecuta oasdiff breaking u openapi-diff en cada PR.
3. Bloquea cambios incompatibles por defecto.
4. Permite excepciones solo con una señal explícita.
5. Ejecuta pruebas de contrato contra staging.
6. Publica reportes de CI para que el autor pueda corregir rápido.

El diff protege la compatibilidad entre versiones del contrato. Las pruebas de contrato protegen la coherencia entre el contrato y la implementación. Necesitas ambos si quieres que una PR no rompa clientes sin que nadie lo note.