Comment connecter Apidog à GitHub et GitLab

Si vos spécifications d'API résident dans Apidog mais que votre source de vérité se trouve dans Git, vous souhaitez que les deux soient en accord. L'intégration Git d'Apidog comble ce fossé. Elle vous permet de connecter un référentiel GitHub, GitLab ou Azure DevOps à votre projet, de pousser vos spécifications OpenAPI dans le contrôle de version, et de récupérer les changements du dépôt dans Apidog. Vous bénéficiez d'un historique d'audit clair, d'une révision de code sur les modifications de spécifications, et d'une sauvegarde qui survit à tout ce qui peut arriver à l'intérieur de l'application.

Ceci est la référence générale. Elle couvre tous les fournisseurs pris en charge par Apidog, les deux façons dont le produit communique avec Git, et les décisions pratiques auxquelles vous serez confronté : quel dépôt, quelle branche, qui peut pousser, et que faire en cas de problème. Si vous avez seulement besoin du guide détaillé pour GitHub, lisez le guide dédié sur la façon de synchroniser votre spécification OpenAPI avec GitHub. Ici, nous allons plus loin.

Ce que fait l'intégration Git d'Apidog

Apidog communique avec Git de deux manières distinctes. Elles résolvent des problèmes différents, et vous pouvez utiliser l'une, l'autre, ou les deux. Les mélanger est la source de confusion la plus courante, alors séparons-les d'abord.

La première capacité est la synchronisation bidirectionnelle via le mode Spec-First. Vous éditez votre document OpenAPI en YAML ou JSON dans l'éditeur de style IDE d'Apidog, validez vos changements et les poussez vers la branche connectée. Lorsque quelqu'un d'autre met à jour la spécification dans le dépôt, vous récupérez ces changements dans Apidog. Il s'agit d'un véritable aller-retour : les modifications sont envoyées vers Git, et les changements du dépôt sont récupérés.

La deuxième capacité est la sauvegarde Git automatique des spécifications d'API. Ici, Apidog exporte le fichier OpenAPI/Swagger de chaque module et le pousse vers un référentiel selon un calendrier. C'est unidirectionnel et automatique. Vous le configurez une fois, et le système conserve une copie versionnée de vos spécifications dans Git sans que vous ayez à lever le petit doigt. C'est un filet de sécurité, pas un flux de travail d'édition.

Gardez cette distinction à l'esprit pour le reste de l'article. Lorsque nous disons « synchronisation », nous faisons référence au flux bidirectionnel du mode Spec-First. Lorsque nous disons « sauvegarde », nous faisons référence à l'exportation planifiée et unidirectionnelle.

Fournisseurs Git pris en charge

Apidog prend en charge les trois fournisseurs les plus utilisés par la plupart des équipes. GitHub et GitLab se connectent directement via leurs flux d'autorisation natifs. Azure DevOps se connecte via une connexion Git générique, qui fonctionne avec tout hôte Git supportant l'authentification HTTPS standard.

La connexion Git générique est la porte de sortie. Si votre hôte ne s'appelle pas GitHub ou GitLab, mais qu'il communique avec Git standard via HTTPS avec authentification par jeton, la connexion générique le gère généralement. Azure DevOps est le cas emblématique, mais le même chemin couvre les configurations auto-hébergées qui exposent une URL de clonage HTTPS.

Connecter votre fournisseur Git

L'étape de connexion est celle où vous accordez à Apidog l'accès nécessaire pour lire et écrire dans votre dépôt. Les mécanismes diffèrent légèrement selon le fournisseur, mais la forme est la même : autoriser, choisir un dépôt, choisir une branche.

Pour GitHub, vous autorisez via l'écran OAuth de GitHub. Apidog demande l'accès au dépôt pour pouvoir lire la spécification et pousser les commits. Si le dépôt appartient à une organisation, GitHub peut acheminer la demande via un administrateur d'organisation qui approuve l'accès tiers. Les dépôts personnels sont autorisés immédiatement sous votre propre compte.

Pour GitLab, le flux reflète GitHub. Vous vous connectez via l'écran OAuth de GitLab et accordez l'accès au dépôt. GitLab auto-hébergé fonctionne tant qu'Apidog peut atteindre l'instance via le réseau.

Pour Azure DevOps, vous utilisez la connexion Git générique. Au lieu d'un échange OAuth, vous fournissez l'URL de clonage HTTPS du dépôt et un jeton d'accès personnel (PAT). Créez le PAT dans Azure DevOps avec la permission de lire et d'écrire du code, puis collez-le dans Apidog. Le jeton est la preuve d'identité qui permet à Apidog de pousser les commits, donc limitez-le exactement aux dépôts dont il a besoin.

Quelques notes de permission qui vous feront gagner du temps :

• Dépôts d'organisation vs personnels. Les dépôts d'organisation nécessitent souvent qu'un administrateur approuve l'intégration une fois. Si votre autorisation semble réussir mais qu'Apidog ne peut pas voir le dépôt, une approbation d'administrateur est généralement manquante.
• Définissez la portée du jeton de manière stricte. Pour Azure DevOps et toute connexion générique, accordez au PAT les droits de lecture/écriture sur le code uniquement pour le projet cible. Évitez les jetons à accès complet au compte.
• Les dépôts privés sont acceptés. Apidog fonctionne avec les dépôts privés. L'accès provient de l'autorisation ou du jeton que vous fournissez, et non de la visibilité publique.

Une fois le fournisseur connecté, vous créez le projet Apidog à partir d'un référentiel et d'une branche, généralement `main`. Cet appariement lie vos spécifications à un emplacement spécifique dans le contrôle de version. Si vous êtes nouveau dans la pratique générale, notre guide sur le contrôle de version OpenAPI avec Git couvre les conventions à adopter avant de tout câbler.

Synchronisation bidirectionnelle avec le mode Spec-First

Le mode Spec-First est l'endroit où la synchronisation bidirectionnelle réside. Il transforme Apidog en un éditeur de spécifications qui s'engage sur Git comme n'importe quel autre code. Vous pouvez lire la référence complète dans la documentation officielle d'Apidog ; voici comment l'aller-retour fonctionne en pratique.

Vous modifiez le document OpenAPI directement en YAML ou JSON. L'éditeur est de type IDE : il vous offre la coloration syntaxique, la validation en direct et l'autocomplétion, de sorte qu'une référence `$ref` mal formée ou un champ obligatoire manquant apparaît pendant que vous tapez plutôt qu'après avoir poussé. Au fur et à mesure que vous modifiez, la barre latérale gauche analyse automatiquement le document en un plan, des chemins, des opérations et des schémas, afin que vous puissiez naviguer dans une grande spécification sans faire défiler le texte brut.

Une modification typique ressemble à ceci. Supposons que vous ajoutiez 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'

Lorsque vous enregistrez cette modification, Apidog la met en scène comme une modification locale. Vous la validez ensuite avec un message et la poussez vers la branche connectée, exactement comme vous le feriez avec n'importe quel flux de travail Git. Une fois le push effectué, un indicateur de synchronisation affiche "Synchronisé à l'instant", confirmant qu'Apidog et la branche contiennent le même contenu.

La direction de la récupération est tout aussi importante. Lorsqu'un coéquipier modifie la spécification dans le dépôt et la pousse, vous récupérez ces changements dans Apidog pour mettre à jour votre copie locale. C'est ce qui rend l'intégration véritablement bidirectionnelle : le dépôt n'est pas seulement une cible de sauvegarde, c'est un pair.

Si vous effectuez des modifications que vous ne souhaitez pas conserver, vous pouvez annuler les modifications non poussées avant de valider. Cela ramène votre copie de travail à l'état de la dernière synchronisation, ce qui est pratique lorsque vous expérimentez et décidez que la modification ne vaut pas la peine d'être conservée.

Ce rythme de commit-and-push est le cœur d'un workflow API Git-native : les modifications de spécifications passent par le même mécanisme de révision, d'historique et de retour en arrière que le reste de votre codebase. Les relecteurs commentent la différence YAML dans une pull request, les approbations bloquent la fusion, et l'historique de votre conception d'API se lit comme l'historique de votre code.

Sauvegarde Git automatique des spécifications d'API

La capacité de sauvegarde est la moitié plus discrète de l'intégration Git d'Apidog, et elle ne vous demande presque rien après la configuration. Vous pointez un module vers un référentiel, et Apidog gère le reste.

Voici le mécanisme. Apidog peut sauvegarder le fichier OpenAPI/Swagger pour chaque module dans un dépôt Git ; GitHub, GitLab et Azure DevOps sont tous pris en charge. Une fois la configuration de sauvegarde enregistrée, le système pousse automatiquement le fichier de spécification OpenAPI du module vers le dépôt spécifié. Le push a lieu pendant une fenêtre aléatoire hors pointe la nuit, ce qui le maintient en dehors de vos heures de travail et répartit la charge.

Ce qui est stocké est le document OpenAPI/Swagger exporté pour ce module, un instantané du contrat d'API tel qu'il est. Parce que chaque push est un commit, vous accumulez un historique de versions dans Git. Vous pouvez comparer le contrat de la semaine dernière avec celui d'aujourd'hui, voir exactement quand un champ a changé, et restaurer une version antérieure directement depuis le dépôt si jamais vous en avez besoin.

Le flux de sauvegarde est unidirectionnel par conception. Apidog écrit dans le dépôt ; il ne récupère pas les modifications à partir de celui-ci. Si vous voulez que les modifications du dépôt soient intégrées dans Apidog, c'est le travail du mode Spec-First, pas de la sauvegarde. Utilisez la sauvegarde lorsque votre objectif est la durabilité et l'historique sans modifier la façon dont votre équipe travaille au quotidien.

Choisir une branche et une structure de dépôt

Les décisions structurelles que vous prenez en amont déterminent la fluidité de l'intégration par la suite. Deux questions dominent : quelle branche et combien de dépôts.

Choix de la branche. La plupart des équipes se synchronisent avec `main` pour la spécification canonique et utilisent des branches de fonctionnalité pour la conception en cours. Pointer Apidog vers une branche de fonctionnalité vous permet d'itérer sur une modification de spécification de manière isolée, d'ouvrir une pull request et de fusionner une fois que la révision est passée. Votre conception d'API suit le même modèle de branchement que votre code. Pointer Apidog directement vers `main` est plus simple mais ignore la validation de révision, donc réservez-le aux petites équipes ou aux changements à faible risque.

Un dépôt ou plusieurs. Il n'y a pas de réponse unique et correcte, mais les compromis sont clairs :

• Un dépôt par API maintient l'historique de chaque spécification propre et ses contrôles d'accès étroits. C'est la solution naturelle lorsque différentes équipes possèdent différentes API.
• Un monorepo pour toutes les spécifications centralise tout et simplifie la recherche et la révision inter-API. Il fonctionne bien lorsqu'une équipe de plateforme possède la surface de l'API. Gardez simplement la disposition des répertoires prévisible, un dossier par module, afin que les sauvegardes et les synchronisations n'entrent pas en collision.

Si vous utilisez un monorepo, attribuez à chaque module son propre chemin. Cela permet de maintenir des sauvegardes automatiques ordonnées et facilite la lecture des différences de spécifications lors de la révision.

Permissions et accès de l'équipe

L'intégration Git touche aux informations d'identification, il est donc important d'être délibéré quant à qui peut faire quoi. Les permissions résident à deux endroits : au sein d'Apidog et au sein de votre fournisseur Git.

Dans Apidog, les permissions d'équipe sont configurées lors de la configuration du projet. C'est là que vous décidez qui peut synchroniser et pousser vers le dépôt connecté. Limitez les droits de push aux personnes qui possèdent la spécification, et laissez tous les autres lire. Cela empêche les pushes accidentels de contributeurs qui ne font que parcourir la conception de l'API.

Au sein de votre fournisseur Git, l'identifiant est important. Pour GitHub et GitLab, l'autorisation OAuth porte l'accès de l'utilisateur qui l'a accordée. Pour Azure DevOps et les connexions génériques, le jeton d'accès personnel est l'identifiant, traitez-le comme un secret. Ne collez pas de jetons dans des documents partagés, limitez-les uniquement aux dépôts cibles et faites-les pivoter à la même fréquence que vous faites pivoter d'autres secrets. Si quelqu'un quitte l'équipe, révoquez son jeton et ré-autorisez-le sous un compte toujours actif.

Le principe est simple : l'intégration n'est aussi sécurisée que le jeton le plus faible derrière elle. Gardez les portées étroites et la propriété claire.

Gérer les conflits de fusion et la dérive

Parce qu'Apidog enregistre un historique Git réel, il hérite du modèle de conflit de Git et des outils de Git pour le résoudre. Les conflits surviennent lorsque deux personnes modifient la même partie de la spécification avant la synchronisation.

Imaginez le scénario. Vous modifiez le schéma `Order` dans Apidog et vous poussez. Un coéquipier a modifié le même schéma côté dépôt et a poussé en premier. Lorsque vous essayez de réconcilier, Git signale un conflit sur le YAML, car les deux parties ont modifié des lignes qui se chevauchent. Ce n'est pas un problème Apidog ; c'est un conflit de fusion Git normal sur un fichier YAML, et vous le résolvez de la manière normale.

Pour éviter les conflits, tirez avant de pousser. Amener le dernier état du dépôt dans Apidog avant de valider vos propres modifications maintient votre copie de travail à jour et réduit la fenêtre où deux modifications entrent en collision. Lorsqu'un conflit survient, résolvez-le sur le YAML de la même manière que vous résoudriez n'importe quel conflit de fusion : choisissez les bonnes lignes, maintenez le document valide et resynchronisez. La validation en direct de l'éditeur aide ici : une fusion bâclée qui rompt la structure OpenAPI apparaît immédiatement plutôt qu'après avoir poussé.

La dérive, où Apidog et le dépôt divergent silencieusement, est la version lente du même problème. L'indicateur "Synchronisé à l'instant" est votre avertissement précoce. S'il n'affiche pas "Synchronisé", quelque chose n'est pas poussé ou n'est pas tiré. Considérez cela comme une incitation à réconcilier avant que l'écart ne se creuse.

Dépannage

La plupart des problèmes d'intégration sont liés à l'authentification, à la sélection de branche ou à une synchronisation interrompue. Parcourez le tableau avant de supposer qu'un problème plus profond est en cause.

Si l'autorisation est le thème récurrent, et c'est généralement le cas, commencez par vérifier que l'identifiant est actif et correctement configuré. Un jeton révoqué ou une approbation d'organisation manquante explique la majorité des rapports "cela a cessé de fonctionner".

FAQ

La synchronisation est-elle unidirectionnelle ou bidirectionnelle ?

Cela dépend de la fonctionnalité que vous utilisez. Le mode Spec-First est bidirectionnel : vous poussez les modifications vers Git et récupérez les changements du dépôt dans Apidog. La sauvegarde automatique est unidirectionnelle : Apidog exporte la spécification de chaque module vers le dépôt selon un calendrier et ne récupère pas les changements.

Où mes spécifications sont-elles stockées ?

Dans le dépôt Git auquel vous vous connectez. Pour le mode Spec-First, votre document OpenAPI se trouve sur la branche vers laquelle vous poussez. Pour la sauvegarde automatique, le fichier OpenAPI/Swagger exporté de chaque module est validé dans le dépôt que vous avez configuré. Dans les deux cas, Git conserve la copie versionnée, et vous gardez le contrôle total du dépôt.

Vers quelle branche dois-je synchroniser ?

Utilisez `main` pour la spécification canonique et des branches de fonctionnalité pour les modifications en cours. La synchronisation vers une branche de fonctionnalité permet à une modification de spécification de passer par une pull request et une révision avant d'être fusionnée, ce qui reflète la façon dont votre code passe déjà par Git.

Que se passe-t-il si mon jeton est révoqué ?

Les pushes commencent à échouer car Apidog n'a plus l'accès en écriture. Ré-autorisez le fournisseur, ou, pour Azure DevOps et les connexions génériques, générez un nouveau jeton d'accès personnel et mettez-le à jour dans Apidog. Une fois l'identifiant restauré, la synchronisation et la sauvegarde reprennent normalement.

Conclusion

L'intégration Git d'Apidog vous offre deux outils complémentaires : la synchronisation bidirectionnelle via le mode Spec-First pour les équipes qui traitent la spécification comme du code, et la sauvegarde automatique par module pour tous ceux qui souhaitent simplement un filet de sécurité versionné. Les deux fonctionnent avec GitHub, GitLab et Azure DevOps, vous pouvez donc connecter le fournisseur que vous utilisez déjà plutôt que d'en adopter un nouveau.

Choisissez la capacité qui correspond à votre objectif. Si vous souhaitez une révision et un historique sur chaque modification de spécification, configurez le mode Spec-First et adoptez le rythme de commit-and-push. Si vous souhaitez une durabilité sans modifier votre workflow, activez la sauvegarde et laissez le push nocturne s'en charger. De nombreuses équipes utilisent les deux. Lorsque vous êtes prêt à le configurer, connectez votre fournisseur, pointez un projet vers un dépôt et une branche, et laissez vos spécifications d'API vivre là où le reste de votre travail se trouve déjà.