¿Cómo se pueden detectar automáticamente los cambios incompatibles en los documentos OpenAPI?

¿Cómo se pueden detectar automáticamente los cambios incompatibles en los documentos OpenAPI? #

Uno de los eventos más disruptivos en un programa de API es un cambio incompatible accidental: una modificación de la API que rompe a los consumidores existentes sin previo aviso. A medida que las API crecen entre equipos, productos y socios externos, revisar manualmente el impacto de cada cambio sobre los consumidores se vuelve poco práctico. La solución es la detección automática de cambios incompatibles, basada en la comparación de documentos OpenAPI entre versiones. Este artículo explica qué constituye un cambio incompatible en OpenAPI, qué herramientas los detectan y cómo integrar esta capacidad en un flujo de trabajo de CI/CD.

¿Qué es un cambio incompatible en OpenAPI? #

Un cambio incompatible es cualquier modificación de una API que hace que los clientes existentes, correctamente escritos, dejen de funcionar. En el contexto de los documentos OpenAPI, los cambios incompatibles incluyen:

Eliminaciones:

  • Eliminar una ruta o una operación de la que dependen los clientes
  • Eliminar un parámetro de solicitud obligatorio
  • Eliminar un campo de respuesta que los clientes leen
  • Eliminar un esquema de seguridad

Adiciones obligatorias:

  • Añadir un nuevo parámetro de solicitud obligatorio o una propiedad obligatoria en el cuerpo de la solicitud: los clientes que no envíen el nuevo campo fallarán ahora en la validación

Cambios de tipo y de formato:

  • Cambiar el tipo de una propiedad (por ejemplo, string → integer)
  • Reducir un enum: eliminar un valor que los clientes pueden enviar
  • Cambiar el nombre de un parámetro de ruta

Cambios de comportamiento expresables en los esquemas:

  • Reducir maxLength: los valores que antes se aceptaban ahora podrían rechazarse
  • Añadir restricciones minLength, minimum, maximum o pattern
  • Cambiar nullable: true por type: string (se elimina la posibilidad de aceptar valores nulos)

Cambios compatibles (los consumidores no se ven afectados):

  • Añadir un nuevo parámetro de solicitud opcional
  • Añadir nuevas propiedades opcionales al cuerpo de una respuesta
  • Añadir una nueva ruta u operación
  • Añadir un nuevo valor de enum (en los enums de respuesta; añadirlo a los enums de solicitud puede ser un cambio incompatible)
  • Relajar restricciones (aumentar maxLength, eliminar minimum)

oasdiff: comparación de OpenAPI de código abierto #

oasdiff es la principal herramienta de código abierto para detectar cambios incompatibles entre dos documentos OpenAPI 3.x. Está escrita en Go y está disponible como herramienta CLI y como biblioteca de Go.

Instalación #

brew install tufin/tufin/oasdiff
# or
go install github.com/tufin/oasdiff@latest

Uso básico #

oasdiff breaking openapi-base.yaml openapi-revision.yaml

La salida enumera cada cambio incompatible con su ubicación y una descripción legible:

1 breaking changes: 1 error, 0 warning
error   [response-property-removed] at ./openapi-revision.yaml
        in API GET /users/{id} response 200/application/json
        removed the response property 'email'

Códigos de salida para la integración con CI #

oasdiff termina con un código distinto de cero cuando encuentra cambios incompatibles, lo que facilita usarlo como una barrera de control en CI:

oasdiff breaking openapi-base.yaml openapi-revision.yaml
if [ $? -ne 0 ]; then
  echo "Breaking changes detected — review required"
  exit 1
fi

Generación de changelog #

oasdiff también puede producir un changelog completo, que enumera tanto los cambios incompatibles como los compatibles entre dos versiones:

oasdiff changelog openapi-base.yaml openapi-revision.yaml

Esto resulta útil para generar notas de la versión o para completar automáticamente el changelog de una API.

openapi-diff #

openapi-diff es una herramienta basada en Java que compara dos documentos OpenAPI y clasifica los cambios como compatibles, incompatibles o desconocidos. Admite OpenAPI 2.0 y 3.x, y puede mostrar los resultados como texto, HTML o JSON.

java -jar openapi-diff.jar openapi-base.yaml openapi-revision.yaml --fail-on-incompatible

El indicador --fail-on-incompatible hace que el proceso termine con un código distinto de cero cuando se detectan cambios incompatibles, algo adecuado para los pipelines de CI.

Optic: detección de cambios incompatibles basada en el tráfico #

Optic adopta un enfoque más completo para la detección de cambios incompatibles. Además de comparar documentos entre sí, Optic puede capturar tráfico real de la API y compararlo con el documento OpenAPI, detectando divergencias entre la especificación y el comportamiento real de la API.

Para los flujos de trabajo con pull requests, Optic se integra directamente con GitHub:

# .github/workflows/api-check.yml
- name: Optic API check
  uses: opticdev/action@v1
  with:
    openapi_path: openapi.yaml

Optic publica un comentario en cada pull request que resume lo que cambió en el documento OpenAPI (los cambios incompatibles en rojo y las adiciones compatibles en verde), lo que da a los revisores visibilidad inmediata del impacto que tienen los cambios de código en la API.

Redocly CLI #

Redocly CLI incluye un comando diff para comparar dos documentos OpenAPI:

redocly diff openapi-base.yaml openapi-revision.yaml

Aunque está menos especializado que oasdiff en la clasificación de cambios incompatibles, el diff de Redocly ofrece un resumen legible que resulta útil durante las revisiones de diseño.

Integración en GitHub Actions #

Un flujo de trabajo completo de detección de cambios incompatibles para GitHub Actions:

name: OpenAPI Breaking Change Check
on:
  pull_request:
    paths:
      - 'openapi.yaml'

jobs:
  breaking-change-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install oasdiff
        run: |
          wget https://github.com/tufin/oasdiff/releases/latest/download/oasdiff_linux_amd64.tar.gz
          tar -xzf oasdiff_linux_amd64.tar.gz
          chmod +x oasdiff

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

      - name: Check for breaking changes
        run: ./oasdiff breaking openapi-base.yaml openapi.yaml --fail-on-err

Este flujo de trabajo se ejecuta en cada pull request que modifique el documento OpenAPI y compara la versión del PR con la de la rama base. Los cambios incompatibles hacen que la comprobación falle, por lo que se requiere una revisión y una aprobación explícitas antes de fusionar.

Control de versiones semántico a partir de los cambios incompatibles #

oasdiff permite sugerir automáticamente la versión semántica según la naturaleza de los cambios detectados:

oasdiff diff openapi-base.yaml openapi-revision.yaml --format json | jq '.breakingChanges | length'

Los equipos pueden usar esto para exigir que:

  • Los PR con cambios incompatibles incrementen la versión mayor.
  • Los PR con adiciones compatibles incrementen la versión menor.
  • Los PR que solo modifiquen la documentación o las descripciones puedan usar una versión de parche.

Gestión de los cambios incompatibles intencionales #

No todos los cambios incompatibles son accidentes. Las obsolescencias planificadas y los incrementos de versión mayor son legítimos. Un flujo de trabajo sólido para los cambios incompatibles lo gestiona de la siguiente manera:

  1. Exigir una etiqueta de excepción: en GitHub, requiere una etiqueta breaking-change-approved en los PR que introduzcan cambios incompatibles intencionales. El flujo de trabajo de CI comprueba esta etiqueta antes de fallar.
  2. Documentar el cambio: exige una entrada de changelog que describa el cambio incompatible y la ruta de migración.
  3. Notificaciones de retirada: usa el indicador deprecated: true de OpenAPI y la extensión x-sunset para comunicar a los consumidores las eliminaciones planificadas con mucha antelación.

Conclusión #

La detección automática de cambios incompatibles transforma la gobernanza de las API de un proceso reactivo, dirigido por incidentes, en una barrera de calidad proactiva. Herramientas como oasdiff, openapi-diff y Optic facilitan la comparación de documentos OpenAPI entre versiones y sacan a la luz los cambios incompatibles antes de que lleguen a los consumidores. Integrar estas herramientas en los flujos de trabajo de CI/CD de los pull requests garantiza que cada cambio en la API se revise en cuanto a su impacto en los consumidores, de modo que los cambios incompatibles accidentales pasen a ser cosa del pasado.

Última actualización: 30 de abril de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.