Cómo Sincronizar una Especificación OpenAPI con GitHub: Dos Métodos

Si su documento OpenAPI reside en un repositorio de Git pero lo edita dentro de un cliente de API, ya conoce la fricción: copie el YAML, péguelo de nuevo, espere que nadie más haya tocado el archivo y rece para que la importación no elimine silenciosamente un campo. Mantener una especificación y un repositorio en concordancia manualmente es el tipo de tarea que falla exactamente cuando tiene prisa.

Esta guía le muestra cómo sincronizar su especificación OpenAPI con GitHub utilizando el Modo Spec-First de Apidog, para que la especificación en su repositorio y la especificación en su editor sigan siendo la misma cosa en lugar de dos copias que reconcilia constantemente. Conectaremos un proveedor, abriremos un proyecto directamente desde un repositorio, editaremos el YAML y enviaremos el cambio a GitHub en una sola pasada. Los mismos pasos funcionan para GitLab.

¡Vamos a ello!

Qué significa realmente la sincronización bidireccional

La sincronización bidireccional significa que las ediciones fluyen en ambas direcciones, automáticamente, sin un paso de exportación intermedio.

• De Apidog a Git: Cuando edita el documento OpenAPI en Apidog y confirma, el cambio se envía a su repositorio como una confirmación Git normal en la rama que eligió.
• De Git a Apidog: Cuando un compañero de equipo (o usted, desde su IDE) envía un cambio a esa rama, Apidog lo recupera para que su editor refleje lo que realmente hay en el repositorio.

El repositorio es la única fuente de verdad. Apidog es un editor rico sobre él. Esa es la idea detrás de un flujo de trabajo de API Git-nativo: la especificación está versionada, revisada y con historial como cualquier otro archivo en su código base, en lugar de residir en una herramienta que exporta periódicamente una instantánea.

Requisitos previos

Antes de comenzar, asegúrese de tener:

• Apidog instalado (aplicación de escritorio o web), con la sesión iniciada.
• Un repositorio de GitHub o GitLab que ya contenga un documento OpenAPI, o uno al que tenga acceso de escritura. Azure DevOps también es compatible a través de Git Connection.
• El Modo Spec-First (beta) activado. Este es el modo que convierte su proyecto en una capa delgada sobre un repositorio Git en lugar del propio almacenamiento de Apidog.

Querrá tener permiso de escritura en la rama con la que planea sincronizar. El acceso de solo lectura le permite extraer, pero no enviar.

Paso 1: Conecte su proveedor de Git

Primero, autorice a Apidog a comunicarse con su proveedor.

1. Abra Apidog y cree un nuevo proyecto, eligiendo el Modo Spec-First.
2. Cuando se le solicite que elija una fuente, seleccione su proveedor, GitHub o GitLab.
3. Haga clic en Autorizar. Su navegador abrirá la pantalla de OAuth del proveedor.
4. Conceda a Apidog acceso a los repositorios que desea sincronizar. En GitHub puede restringir esto a repositorios específicos en lugar de a toda su cuenta.

Una vez completada la autorización, regresará a Apidog con el proveedor conectado. Esto solo se hace una vez por proveedor, los proyectos futuros reutilizan la conexión.

Para la referencia completa sobre este flujo, incluyendo Azure DevOps a través de Git Connection, consulte la documentación del Modo Spec-First.

Paso 2: Cree un proyecto a partir de un repositorio y una rama

Ahora apunte Apidog a la especificación real.

1. Con el proveedor conectado, elija el repositorio que contiene su archivo OpenAPI.
2. Seleccione la rama con la que desea sincronizar, generalmente main. Esta es la rama en la que se aplicarán sus confirmaciones y la rama que Apidog observa en busca de cambios entrantes.
3. Confirme la ruta al documento OpenAPI si Apidog lo solicita (por ejemplo, openapi.yaml en la raíz del repositorio, o bajo docs/).
4. Cree el proyecto.

Apidog clona la especificación de esa rama y la abre. La barra lateral izquierda se llena con sus puntos finales y esquemas, porque Apidog analizó el documento en un esquema navegable. Ahora está viendo la especificación del repositorio, en vivo.

Paso 3: Edite su YAML de OpenAPI en el editor de código

El Modo Spec-First le proporciona un editor estilo IDE para el YAML de OpenAPI en bruto, con resaltado de sintaxis, validación en línea y autocompletado. Usted escribe OpenAPI directamente; Apidog mantiene el esquema visual actualizado a medida que escribe.

Añadamos un pequeño punto final. Suponga que desea una verificación de estado:

paths:
 /health:
 get:
 summary: Service health check
 operationId: getHealth
 responses:
 '200':
 description: Service is up
 content:
 application/json:
 schema:
 type: object
 properties:
 status:
 type: string
 example: ok

Mientras escribe, suceden dos cosas. La barra lateral izquierda analiza automáticamente el esquema, por lo que su nueva operación /health aparece en el árbol de inmediato. Y el validador marca los problemas en línea, un bloque responses faltante, un $ref incorrecto, un error de indentación, antes de que usted confirme. Si el YAML está mal formado, lo verá subrayado en lugar de descubrirlo más tarde en una canalización fallida.

Aquí también es donde el control de versiones hace su trabajo. Si desea una mirada más profunda sobre cómo se desarrollan las diferencias y el historial en una especificación, la guía sobre control de versiones de OpenAPI con Git lo explica.

Paso 4: Confirmar y enviar

Cuando la edición se vea correcta, envíela a GitHub.

1. Abra el panel de confirmación (el área de Git/control de código fuente del proyecto).
2. Revise el cambio. Apidog muestra lo que se ha modificado con respecto a la versión sincronizada.
3. Escriba un mensaje de confirmación, trátelo como cualquier confirmación: Add /health endpoint.
4. Haga clic en Confirmar y Enviar.

Apidog confirma a la rama elegida y envía al remoto. Abra su repositorio en GitHub y verá la confirmación en el historial de la rama, con la autoría esperada, afectando exactamente al archivo OpenAPI.

¿Ha cambiado de opinión antes de enviar? Puede descartar ediciones no enviadas para revertir el documento al último estado sincronizado. Nada sale de Apidog hasta que usted confirma, por lo que los experimentos locales permanecen locales.

Paso 5: Verifique el estado de sincronización

Apidog muestra un indicador de sincronización para que siempre sepa dónde se encuentra.

Después de un envío exitoso, el indicador mostrará "Sincronizado hace un momento". Esa es su confirmación de que el editor y la rama remota tienen el mismo documento. Con el tiempo se actualiza ("Sincronizado hace 5 minutos") y, cuando otra persona envía un cambio, Apidog extrae el cambio y reinicia el indicador después de reconciliarlo.

Si el indicador muestra un estado pendiente o desactualizado, le está diciendo que la copia local y la remota han divergido, lo que le indica que debe extraer o resolver antes de continuar.

Solución de problemas

Algunas cosas suelen confundir a la gente la primera vez.

• Autorización caducada o revocada. Si los envíos comienzan a fallar con un error de permiso, vuelva a ejecutar la autorización del Paso 1. Los tokens pueden ser revocados por el proveedor o simplemente caducar.
• Rama incorrecta. El envío a una rama main protegida que requiere solicitudes de extracción será rechazado. Sincronice con una rama de características o ajuste las reglas de protección de la rama. Verifique que la rama elegida en el Paso 2 coincida con donde espera que lleguen las confirmaciones.
• Conflictos de fusión. Si un compañero de equipo envió un cambio a la misma rama mientras usted estaba editando, el remoto avanzó su copia local. Extraiga lo último, concilie el YAML superpuesto y confirme de nuevo. Debido a que la especificación es texto plano, los conflictos se resuelven de la misma manera que cualquier conflicto de código.
• Los errores de validación bloquean su flujo. Apidog no le impedirá confirmar un YAML no válido, pero debe corregir primero lo que el validador en línea le señala. Una especificación limpia mantiene sus documentos generados, simulaciones y pruebas honestos.

Preguntas frecuentes

¿La sincronización con GitHub también funciona con GitLab y Azure DevOps?

Sí. El Modo Spec-First es compatible directamente con GitHub y GitLab, y con Azure DevOps a través de Git Connection. El flujo de conectar-editar-confirmar-enviar es el mismo en los tres; solo la pantalla de autorización difiere según el proveedor.

¿Qué sucede si un compañero de equipo edita la especificación en el repositorio mientras yo estoy trabajando en Apidog?

Apidog vuelve a traer su cambio a su editor como parte de la sincronización bidireccional. Si sus ediciones y las suyas afectan a diferentes partes del archivo, se fusionarán limpiamente. Si se superponen, resolverá un conflicto de Git estándar, como lo haría en cualquier archivo de texto.

¿Puedo deshacer un cambio antes de que llegue a GitHub?

Sí. Hasta que haga clic en Confirmar y Enviar, sus ediciones son locales. Utilice descartar ediciones no enviadas para revertir el documento al último estado sincronizado, y nada llegará al remoto.