Si sus especificaciones de API residen en Apidog pero su fuente de verdad vive en Git, querrá que ambas estén de acuerdo. La integración Git de Apidog cierra esa brecha. Le permite conectar un repositorio de GitHub, GitLab o Azure DevOps a su proyecto, enviar sus especificaciones OpenAPI al control de versiones y extraer los cambios del repositorio de vuelta a Apidog. Obtiene un rastro de auditoría limpio, revisión de código sobre los cambios de especificación y una copia de seguridad que sobrevive a cualquier cosa que suceda dentro de la aplicación.
Esta es la referencia general. Cubre todos los proveedores que Apidog soporta, ambas formas en que el producto se comunica con Git, y las decisiones prácticas a las que se enfrentará: qué repositorio, qué rama, quién puede hacer push y qué hacer cuando algo falla. Si solo necesita la guía detallada de GitHub, lea la guía dedicada sobre cómo sincronizar su especificación OpenAPI con GitHub. Aquí, vamos más allá.
Qué hace la integración Git de Apidog
Apidog se comunica con Git de dos maneras distintas. Resuelven problemas diferentes, y puede usar una, la otra o ambas. Confundirlas es la fuente de confusión más común, así que vamos a separarlas primero.
La primera capacidad es la sincronización bidireccional a través del Modo Spec-First. Usted edita su documento OpenAPI como YAML o JSON dentro del editor estilo IDE de Apidog, confirma sus cambios y los envía a la rama conectada. Cuando alguien más actualiza la especificación en el repositorio, usted extrae esos cambios de vuelta a Apidog. Este es un verdadero viaje de ida y vuelta: las ediciones fluyen hacia Git, y los cambios del repositorio fluyen de vuelta.
La segunda capacidad es la copia de seguridad automática de Git de las especificaciones de API. Aquí, Apidog exporta el archivo OpenAPI/Swagger de cada módulo y lo envía a un repositorio según un cronograma. Esto es unidireccional y sin intervención. Lo configura una vez, y el sistema mantiene una copia versionada de sus especificaciones en Git sin que usted tenga que mover un dedo. Es una red de seguridad, no un flujo de trabajo de edición.
| Capacidad | Dirección | Disparador | Mejor para |
|---|---|---|---|
| Sincronización en Modo Spec-First | Bidireccional (push y pull) | Commit/push manual, pull manual | Equipos que tratan la especificación como código y desean revisión en cada cambio |
| Copia de seguridad automática de Git | Unidireccional (Apidog → Git) | Programado, fuera de horas pico | Cualquiera que desee una copia de seguridad versionada sin cambiar su forma de trabajar |
Tenga esta distinción en cuenta para el resto del artículo. Cuando decimos "sincronización", nos referimos al flujo bidireccional del Modo Spec-First. Cuando decimos "copia de seguridad", nos referimos a la exportación unidireccional programada.
Proveedores Git soportados
Apidog soporta los tres proveedores que la mayoría de los equipos ya utilizan. GitHub y GitLab se conectan directamente a través de sus flujos de autorización nativos. Azure DevOps se conecta a través de una conexión Git genérica, que funciona con cualquier host Git que admita la autenticación HTTPS estándar.
| Proveedor | Método de autenticación | Notas |
|---|---|---|
| GitHub | Autorización OAuth (inicio de sesión de GitHub) | Funciona con repositorios personales y de organización. Los repositorios de organización pueden requerir que un administrador apruebe la conexión. |
| GitLab | Autorización OAuth (inicio de sesión de GitLab) | Soporta gitlab.com e instancias autoalojadas accesibles desde Apidog. |
| Azure DevOps | Conexión Git genérica (HTTPS + token) | Conéctese a través de la URL HTTPS del repositorio y un token de acceso personal con ámbito de repositorio. |
La conexión Git genérica es la vía de escape. Si su host no es GitHub o GitLab por nombre, pero admite Git estándar sobre HTTPS con autenticación por token, la conexión genérica suele manejarlo. Azure DevOps es el caso principal, pero el mismo camino cubre configuraciones autoalojadas que exponen una URL de clonación HTTPS.
Conectando su proveedor Git
El paso de conexión es donde usted otorga a Apidog el acceso que necesita para leer y escribir en su repositorio. La mecánica difiere ligeramente por proveedor, pero la forma es la misma: autorizar, elegir un repositorio, elegir una rama.
Para GitHub, usted autoriza a través de la pantalla OAuth de GitHub. Apidog solicita acceso al repositorio para poder leer la especificación y enviar commits. Si el repositorio pertenece a una organización, GitHub puede enrutar la solicitud a través de un administrador de la organización que apruebe el acceso de terceros. Los repositorios personales se autorizan inmediatamente bajo su propia cuenta.
Para GitLab, el flujo es similar a GitHub. Usted inicia sesión a través de la pantalla OAuth de GitLab y concede acceso al repositorio. GitLab autogestionado funciona siempre que Apidog pueda acceder a la instancia a través de la red.
Para Azure DevOps, utiliza la conexión Git genérica. En lugar de un handshake OAuth, usted proporciona la URL de clonación HTTPS del repositorio y un token de acceso personal (PAT). Cree el PAT en Azure DevOps con permiso para leer y escribir código, luego péguelo en Apidog. El token es la credencial que permite a Apidog enviar commits, así que delimite su alcance exactamente a los repositorios que necesita.
Algunas notas sobre permisos que ahorran tiempo:
- Repositorios de organización vs. personales. Los repositorios de organización a menudo requieren que un administrador apruebe la integración una vez. Si su autorización parece exitosa pero Apidog no puede ver el repositorio, generalmente falta una aprobación del administrador.
- Limite estrictamente el alcance del token. Para Azure DevOps y cualquier conexión genérica, otorgue al PAT permisos de lectura/escritura de código solo para el proyecto de destino. Evite los tokens de cuenta completa.
- Los repositorios privados están bien. Apidog funciona con repositorios privados. El acceso proviene de la autorización o el token que usted proporciona, no de la visibilidad pública.
Una vez conectado el proveedor, usted crea el proyecto Apidog a partir de un repositorio más una rama, normalmente main. Ese emparejamiento es lo que vincula sus especificaciones a un lugar específico en el control de versiones. Si es nuevo en la práctica más amplia, nuestra guía sobre control de versiones de OpenAPI con Git cubre las convenciones que vale la pena adoptar antes de configurar todo.
Sincronización bidireccional con el Modo Spec-First
El Modo Spec-First es donde reside la sincronización bidireccional. Convierte Apidog en un editor de especificaciones que hace commits a Git como cualquier otro código. Puede leer la referencia completa en la documentación oficial de Apidog; así es como funciona el viaje de ida y vuelta en la práctica.
Usted edita el documento OpenAPI directamente como YAML o JSON. El editor es de estilo IDE: le proporciona resaltado de sintaxis, validación en vivo y autocompletado, por lo que un $ref mal formado o un campo requerido faltante aparecen mientras escribe, en lugar de después de hacer push. A medida que edita, la barra lateral izquierda analiza automáticamente el documento en un esquema, rutas, operaciones y esquemas, para que pueda navegar por una especificación grande sin desplazarse por el texto sin formato.
Una edición típica se ve así. Digamos que añade un endpoint:
paths:
/v1/orders/{orderId}:
get:
operationId: getOrder
summary: Retrieve a single order
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
Cuando guarda ese cambio, Apidog lo prepara como una edición local. Luego lo confirma con un mensaje y lo envía a la rama conectada, exactamente como lo haría con cualquier flujo de trabajo de Git. Después de que el push se completa, un indicador de sincronización dice "Sincronizado justo ahora", su confirmación de que Apidog y la rama tienen el mismo contenido.
La dirección de pull es igual de importante. Cuando un compañero de equipo edita la especificación en el repositorio y hace push, usted extrae esos cambios a Apidog para actualizar su copia local. Esto es lo que hace que la integración sea realmente bidireccional: el repositorio no es solo un objetivo de copia de seguridad, es un par.
Si realiza ediciones que no desea conservar, puede descartar las ediciones no enviadas antes de confirmar. Esto revierte su copia de trabajo para que coincida con el último estado sincronizado, lo cual es útil cuando está experimentando y decide que el cambio no vale la pena.
Este ritmo de commit y push es el corazón de un flujo de trabajo de API nativo de Git: los cambios de especificación pasan por la misma maquinaria de revisión, historial y reversión que el resto de su código base. Los revisores comentan el diff de YAML en una solicitud de extracción, las aprobaciones controlan la fusión y el historial de diseño de su API se lee como el historial de su código.
Copia de seguridad automática de Git de las especificaciones de API
La capacidad de copia de seguridad es la mitad más silenciosa de la integración Git de Apidog, y no requiere casi nada de usted después de la configuración. Usted apunta un módulo a un repositorio, y Apidog se encarga del resto.
Aquí está el mecanismo. Apidog puede hacer una copia de seguridad del archivo OpenAPI/Swagger de cada módulo en un repositorio Git; GitHub, GitLab y Azure DevOps son todos compatibles. Una vez que guarda la configuración de la copia de seguridad, el sistema envía automáticamente el archivo de especificación OpenAPI del módulo al repositorio especificado. El envío ocurre durante una ventana nocturna aleatoria fuera de horas pico, lo que lo mantiene fuera de sus horas de trabajo y distribuye la carga.
Lo que se almacena es el documento OpenAPI/Swagger exportado para ese módulo, una instantánea del contrato de la API tal como está. Debido a que cada push es un commit, usted acumula un historial de versiones en Git. Puede diferenciar el contrato de la semana pasada con el de hoy, ver exactamente cuándo cambió un campo y restaurar una versión anterior directamente desde el repositorio si alguna vez lo necesita.
El flujo de copia de seguridad es unidireccional por diseño. Apidog escribe en el repositorio; no lee los cambios de vuelta. Si desea que las ediciones del repositorio fluyan a Apidog, ese es el trabajo del Modo Spec-First, no de la copia de seguridad. Utilice la copia de seguridad cuando su objetivo sea la durabilidad y el historial sin alterar cómo trabaja su equipo día a día.
Eligiendo una rama y estructura de repositorio
Las decisiones estructurales que tome al principio configuran lo fluida que se sentirá la integración más tarde. Dominan dos preguntas: qué rama y cuántos repositorios.
Elección de la rama. La mayoría de los equipos sincronizan con main para la especificación canónica y usan ramas para el diseño en curso. Apuntar Apidog a una rama le permite iterar sobre un cambio de especificación de forma aislada, abrir una solicitud de extracción y fusionar una vez que la revisión pasa; el diseño de su API sigue el mismo modelo de ramificación que su código. Apuntar Apidog directamente a main es más simple pero omite la puerta de revisión, así que resérvelo para equipos pequeños o cambios de bajo riesgo.
Un repositorio o muchos. No hay una única respuesta correcta, pero las ventajas y desventajas son claras:
- Un repositorio por API mantiene el historial de cada especificación limpio y sus controles de acceso restringidos. Es la opción natural cuando diferentes equipos poseen diferentes APIs.
- Un monorepo para todas las especificaciones centraliza todo y simplifica la búsqueda y revisión entre APIs. Funciona bien cuando un equipo de plataforma es propietario de la superficie de la API. Solo mantenga la estructura de directorios predecible, una carpeta por módulo, para que las copias de seguridad y las sincronizaciones no colisionen.
Si utiliza un monorepo, asigne a cada módulo su propia ruta. Esto mantiene las copias de seguridad automáticas ordenadas y facilita la lectura de las diferencias de especificación en la revisión.
Permisos y acceso del equipo
La integración Git involucra credenciales, por lo que vale la pena ser deliberado sobre quién puede hacer qué. Los permisos residen en dos lugares: dentro de Apidog y dentro de su proveedor Git.
Dentro de Apidog, los permisos del equipo se configuran durante la configuración del proyecto. Ahí es donde decide quién puede sincronizar y enviar al repositorio conectado. Limite los derechos de push a las personas que poseen la especificación, y permita que todos los demás lean. Esto evita pushes accidentales de colaboradores que solo están navegando por el diseño de la API.
Dentro de su proveedor Git, la credencial es importante. Para GitHub y GitLab, la autorización OAuth lleva el acceso del usuario que la otorgó. Para Azure DevOps y conexiones genéricas, el token de acceso personal es la credencial, trátelo como un secreto. No pegue tokens en documentos compartidos, limítelos solo a los repositorios de destino y rótelos con la misma frecuencia con la que rota otros secretos. Si alguien deja el equipo, revoque su token y vuelva a autorizar bajo una cuenta que todavía esté activa.
El principio es simple: la integración es tan segura como el token más débil detrás de ella. Mantenga los alcances estrechos y la propiedad clara.
Manejo de conflictos de fusión y desincronización
Debido a que Apidog registra un historial Git real, hereda el modelo de conflictos de Git y las herramientas de Git para resolverlos. Los conflictos ocurren cuando dos personas cambian la misma parte de la especificación antes de sincronizar.
Imagine el escenario. Usted edita el esquema Order en Apidog y hace push. Un compañero de equipo editó el mismo esquema en el repositorio y hizo push primero. Cuando intenta reconciliar, Git marca un conflicto en el YAML, porque ambas partes cambiaron líneas superpuestas. Esto no es un problema de Apidog; es un conflicto de fusión de Git normal en un archivo YAML, y lo resuelve de la manera habitual.
Para evitar conflictos, haga un pull antes de hacer un push. Traer el último estado del repositorio a Apidog antes de confirmar sus propios cambios mantiene su copia de trabajo actualizada y reduce la ventana en la que dos ediciones chocan. Cuando surge un conflicto, resuélvalo en el YAML de la misma manera que resolvería cualquier conflicto de fusión: elija las líneas correctas, mantenga el documento válido y vuelva a sincronizar. La validación en vivo del editor ayuda aquí, una fusión fallida que rompe la estructura de OpenAPI aparece inmediatamente en lugar de después de hacer push.
La desincronización, donde Apidog y el repositorio divergen silenciosamente, es la versión lenta del mismo problema. El indicador "Sincronizado justo ahora" es su advertencia temprana. Si no muestra sincronizado, algo no ha sido enviado (pushed) o extraído (pulled). Tómelo como un aviso para reconciliar antes de que la brecha se amplíe.
Solución de problemas
La mayoría de los problemas de integración se remontan a la autenticación, la selección de la rama o una sincronización interrumpida. Revise la tabla antes de asumir que algo más profundo está mal.
| Síntoma | Causa probable | Solución |
|---|---|---|
| La autorización falla o el repositorio no aparece | La organización no ha aprobado el acceso de terceros, o el token carece de alcance | Haga que un administrador de la organización apruebe la aplicación de GitHub/GitLab; para Azure DevOps, reemita el PAT con ámbito de código de lectura/escritura |
| Push rechazado | Token revocado o caducado, o sin permiso de escritura | Vuelva a autorizar el proveedor; para conexiones genéricas, genere un PAT nuevo y actualícelo en Apidog |
| Cambios enviados (pushed) pero no visibles | Apuntando a la rama incorrecta | Confirme que la rama conectada coincide con donde espera los commits; cambie de rama en la configuración del proyecto |
| Sincronización atascada o “Sincronizado justo ahora” nunca aparece | Ediciones locales no enviadas (unpushed), o se necesita un pull | Confirme y envíe las ediciones pendientes; si un compañero de equipo envió, haga pull primero y luego vuelva a sincronizar |
| Conflicto de fusión en la especificación | Dos ediciones en las mismas líneas | Resuelva el conflicto YAML normalmente, mantenga el documento válido, vuelva a sincronizar |
| La copia de seguridad no se ejecutó | El push programado aún no ha alcanzado su ventana fuera de horas pico | Las copias de seguridad se envían durante una ventana nocturna aleatoria; espere al siguiente ciclo o verifique la configuración del repositorio/rama de la copia de seguridad |
| Ediciones que no pretendía guardar | Cambios experimentales antes del commit | Use “descartar ediciones no enviadas” para revertir al último estado sincronizado |
Si la autorización es el tema recurrente, y generalmente lo es, comience por confirmar que la credencial está activa y tiene el alcance correcto. Un token revocado o una aprobación de organización faltante explican la mayoría de los informes de "simplemente dejó de funcionar".
Preguntas Frecuentes
¿La sincronización es unidireccional o bidireccional?
Depende de la capacidad que esté utilizando. El Modo Spec-First es bidireccional: usted envía ediciones a Git y extrae los cambios del repositorio de vuelta a Apidog. La copia de seguridad automática es unidireccional: Apidog exporta la especificación de cada módulo al repositorio según un cronograma y no lee los cambios de vuelta.
¿Dónde se almacenan mis especificaciones?
En el repositorio Git al que se conecta. Para el Modo Spec-First, su documento OpenAPI reside en la rama a la que hace push. Para la copia de seguridad automática, el archivo OpenAPI/Swagger exportado de cada módulo se confirma en el repositorio que configuró. En ambos casos, Git mantiene la copia versionada y usted conserva el control total del repositorio.
¿A qué rama debo sincronizar?
Use main para la especificación canónica y las ramas para los cambios en curso. La sincronización con una rama permite que un cambio de especificación pase por una solicitud de extracción y revisión antes de que se fusione, lo que refleja cómo su código ya se mueve a través de Git.
¿Qué sucede si se revoca mi token?
Los pushes comienzan a fallar porque Apidog ya no tiene acceso de escritura. Vuelva a autorizar el proveedor o, para Azure DevOps y conexiones genéricas, genere un nuevo token de acceso personal y actualícelo en Apidog. Una vez que la credencial se restaura, la sincronización y la copia de seguridad se reanudan normalmente.
Conclusión
La integración Git de Apidog le proporciona dos herramientas complementarias: la sincronización bidireccional a través del Modo Spec-First para equipos que tratan la especificación como código, y la copia de seguridad automática por módulo para cualquiera que simplemente quiera una red de seguridad versionada. Ambas funcionan con GitHub, GitLab y Azure DevOps, por lo que conecta el proveedor que ya utiliza en lugar de adoptar uno nuevo.
Elija la capacidad que coincida con su objetivo. Si desea revisión e historial en cada cambio de especificación, configure el Modo Spec-First y adopte el ritmo de commit y push. Si desea durabilidad sin cambiar su flujo de trabajo, active la copia de seguridad y deje que el push nocturno se encargue. Muchos equipos ejecutan ambas. Cuando esté listo para configurarlo, conecte su proveedor, apunte un proyecto a un repositorio y rama, y deje que sus especificaciones de API vivan donde ya reside el resto de su trabajo.