Cómo Controlar Versiones de un Archivo OpenAPI con Git

Tu especificación OpenAPI es un contrato. Cuando se desvía, los clientes se rompen, los simulacros se vuelven obsoletos y las pruebas se ejecutan contra una API que ya no existe. Así que trata la especificación como el resto de tu código: ponla en Git, crea ramas, revísala y valídala en cada cambio.

Esta guía te mostrará el control de versiones de OpenAPI con Git desde cero. Dónde reside el archivo, cómo crear ramas, qué buscan realmente los revisores en una diferencia de especificación y cómo enviar cambios directamente desde Apidog. Al final, tendrás un flujo de trabajo en el que todo tu equipo podrá confiar.

Por qué controlar las versiones de tu especificación OpenAPI

Una especificación que reside en una wiki o en una unidad compartida no tiene historial. No puedes ver quién cambió la carga útil de POST /orders el martes pasado, ni por qué. Git lo soluciona.

Pon openapi.yaml bajo control de versiones y obtendrás cuatro cosas gratis:

• Historial. Cada cambio es un commit con un autor, una marca de tiempo y un mensaje.
• Blame. git blame openapi.yaml te dice quién añadió ese campo requerido y cuándo.
• Reversión. ¿Una fusión errónea que rompió el contrato? Revierte el commit y volverás a una especificación que funciona.
• Revisión. Los cambios en la especificación pasan por solicitudes de extracción (pull requests), por lo que una segunda persona ve la diferencia antes de que se implemente.

Esta es la base de un flujo de trabajo de API nativo de Git: la especificación es código fuente, y el código fuente vive en Git.

Dónde reside el archivo de la especificación en el repositorio

Mantenlo simple y predecible. La mayoría de los equipos colocan un solo archivo openapi.yaml en la raíz del repositorio o en una carpeta api/:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

Cuando mantienes varias versiones principales en paralelo, sepáralas por versión con un archivo por cada versión principal:

api/
├── api-v1.yaml
└── api-v2.yaml

Esto mantiene los cambios que rompen la compatibilidad aislados. api-v1.yaml permanece congelado para los clientes existentes mientras que api-v2.yaml evoluciona. También hace que las diferencias sean más pequeñas y la revisión más rápida, porque cada archivo cambia por una razón. Tratar la especificación de esta manera es la idea central detrás de la especificación de API como código.

Elige una convención y documéntala. El peor resultado es que dos archivos afirmen ser "la" especificación.

Estrategias de ramificación para cambios en la especificación

No necesitas un modelo de ramificación especial para las especificaciones. Reutiliza lo que tu código ya hace. Crea una rama a partir de main, haz el cambio, abre una PR.

Convención de nombres que facilita la revisión de las ramas de especificación:

El prefijo api/ indica "esta PR afecta al contrato" de un vistazo. Los revisores y la CI pueden filtrarla. Para los cambios que rompen la compatibilidad, el prefijo explícito breaking- es una señal de que esto necesita atención adicional y probablemente un aumento de versión.

Mantén las ramas de corta duración. Una rama de especificación que viva dos semanas chocará con los cambios de todos los demás. Las ramas pequeñas y enfocadas se fusionan limpiamente.

Revisión de cambios de especificación en una solicitud de extracción

Aquí es donde el control de versiones demuestra su valía. Una PR de especificación es un cambio de contrato, y los cambios de contrato merecen una revisión real.

Escribe YAML de una manera que facilite la diferencia para que los revisores puedan leer el cambio, no luchar con el formato:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

La indentación consistente y una propiedad por línea significan que la adición de un solo campo aparece como una diferencia de una sola línea. Ese es el objetivo.

Lo que los revisores deben verificar:

• Cambios que rompen la compatibilidad. ¿Se añadió un campo requerido a una solicitud? ¿Se eliminó o renombró un campo de respuesta? ¿Perdió una enumeración un valor? Cada uno de ellos puede romper clientes existentes.
• Compatibilidad hacia atrás. Los nuevos campos opcionales y los nuevos endpoints son seguros. Los cambios en las formas existentes no lo son.
• Nomenclatura y consistencia. ¿El nuevo endpoint coincide con el uso de mayúsculas/minúsculas y la pluralización del resto de la API?
• Completitud. Cada nueva operación necesita un summary, esquemas de respuesta y respuestas de error.
• Ejemplos. Los ejemplos realistas hacen que la documentación y los simulacros sean útiles.

Para la detección de cambios que rompen la compatibilidad, apóyate en herramientas en lugar de la vista. Un paso de CI (cubierto a continuación) puede comparar la especificación de la PR con la de main y fallar la compilación si detecta un cambio incompatible. Los humanos los pasan por alto; las herramientas de diferencia no.

Commit y push desde Apidog

Editar YAML sin procesar a mano funciona, pero un editor visual con validación en vivo es más rápido y detecta errores antes. El modo Spec-First de Apidog te ofrece sincronización bidireccional con Git: edita la especificación en la UI, haz commit y push a tu repositorio sin salir de la herramienta. Recupera los cambios de un compañero de equipo de la misma manera.

El flujo se ve así:

1. Conecta tu repositorio Git y apunta Apidog al archivo de la especificación.
2. Edita endpoints, esquemas y ejemplos en el editor visual.
3. Apidog escribe YAML limpio y fácil de diferenciar de nuevo en el archivo.
4. Haz commit en una rama y push, luego abre tu PR como de costumbre.

Debido a que Apidog serializa YAML de manera consistente, tus diferencias se mantienen pequeñas y revisables, sin reordenamientos ruidosos o reformateos. Puedes leer la configuración completa en la documentación del modo Spec-First de Apidog. Si quieres que el archivo se coloque en un proveedor específico, consulta sincronizar tu especificación OpenAPI con GitHub.

Ganchos de validación de CI

Nunca permitas que una especificación no válida llegue a main. Conecta la validación a tus comprobaciones de solicitud de extracción para que un contrato roto falle la compilación automáticamente.

Un paso mínimo de GitHub Actions:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Añade más comprobaciones a medida que creces:

• Linter la especificación en busca de problemas estructurales y de estilo.
• Validar que se analiza como OpenAPI 3.x legal.
• Comparar con main para detectar cambios que rompen la compatibilidad y señalarlos en la PR.

Estas comprobaciones se ejecutan en segundos y detectan los errores que un revisor humano pasaría por alto.

Mejores prácticas

Algunos hábitos mantienen saludable el control de versiones de la especificación a lo largo del tiempo:

• Usa versionado semántico. Incrementa el campo info.version. Un cambio que rompe la compatibilidad significa una nueva versión principal; las adiciones compatibles hacia atrás incrementan la versión menor.
• Mantén un registro de cambios. Un breve archivo CHANGELOG.md junto a la especificación les dice a los consumidores qué se movió entre versiones.
• Envía diferencias pequeñas. Un cambio lógico por PR. Las PR grandes de especificaciones ocultan cambios que rompen la compatibilidad en el ruido.
• Escribe mensajes de commit descriptivos. "Añadir refundReason a la solicitud de reembolso" es mejor que "actualizar especificación".
• Nunca edites la especificación fusionada directamente en main. Siempre crea una rama, incluso para un error tipográfico.

Preguntas frecuentes

¿Cómo detecto cambios que rompen la compatibilidad en una especificación OpenAPI?

Ejecuta una herramienta de diferencia de especificaciones en CI que compare la solicitud de extracción con la versión en main. Herramientas como oasdiff clasifican cada cambio como rompedor, no rompedor o no clasificado, y pueden fallar la compilación si hay uno rompedor. Esto detecta campos eliminados, nuevos parámetros requeridos y tipos modificados que una revisión manual podría pasar por alto.

¿Debo mantener un solo archivo OpenAPI o dividirlo en varios?

Comienza con un único archivo openapi.yaml. Es el más fácil de revisar y versionar. Cuando el archivo se haga grande o mantengas varias versiones principales en paralelo, divídelo por versión principal (api-v1.yaml, api-v2.yaml) o usa $ref para dividir los esquemas en archivos separados. No dividas prematuramente; un archivo legible es mejor que cinco fragmentados.

¿Puedo controlar las versiones de mi especificación sin escribir YAML a mano?

Sí. El modo Spec-First de Apidog te permite editar la especificación en un editor visual y sincronizar los cambios con Git en ambas direcciones. Escribe YAML consistente, por lo que tus diferencias se mantienen limpias y tus solicitudes de extracción siguen siendo legibles, mientras sigues obteniendo el historial completo de Git y la revisión.