Comment synchroniser une spécification OpenAPI avec GitHub : 2 méthodes

Si votre document OpenAPI est dans un dépôt Git mais que vous le modifiez dans un client API, vous connaissez les frictions : copier-coller le YAML, vérifier que personne n’a modifié le fichier entre-temps, puis espérer que l’import n’a pas supprimé un champ. Pour éviter ces écarts, synchronisez directement votre spécification OpenAPI avec GitHub depuis Apidog en mode Spec-First.

Essayez Apidog aujourd’hui

Dans ce guide, vous allez connecter un fournisseur Git, ouvrir un projet depuis un dépôt, modifier le YAML OpenAPI, puis pousser le changement vers GitHub. Les mêmes étapes s’appliquent à GitLab. Azure DevOps est également pris en charge via Git Connection.

Ce que signifie la synchronisation bidirectionnelle

La synchronisation bidirectionnelle évite les exports/imports manuels.

• Apidog vers Git : vous modifiez le document OpenAPI dans Apidog, puis vous commitez et poussez la modification vers la branche choisie.
• Git vers Apidog : si vous ou un membre de l’équipe poussez une modification depuis un IDE ou un autre outil, Apidog récupère la version à jour du dépôt.

Le dépôt reste la source unique de vérité. Apidog agit comme un éditeur riche au-dessus du fichier versionné. C’est le principe d’un workflow API Git-native : votre spécification est revue, historisée et versionnée comme le reste du code.

Prérequis

Avant de commencer, vérifiez que vous avez :

• Apidog installé, via l’application de bureau ou web.
• Un dépôt GitHub ou GitLab contenant déjà un document OpenAPI, ou un dépôt sur lequel vous avez un accès en écriture.
• Le mode Spec-First (bêta) activé.
• Une permission d’écriture sur la branche à synchroniser.

Un accès en lecture seule permet de récupérer la spécification, mais pas de pousser des commits.

Étape 1 : connectez votre fournisseur Git

Autorisez d’abord Apidog à accéder à votre fournisseur Git.

1. Ouvrez Apidog.
2. Créez un nouveau projet.
3. Sélectionnez le mode Spec-First.
4. Choisissez votre fournisseur : GitHub ou GitLab.
5. Cliquez sur Autoriser.
6. Dans l’écran OAuth du fournisseur, accordez l’accès aux dépôts nécessaires.

Sur GitHub, vous pouvez limiter l’accès à des dépôts spécifiques au lieu de donner accès à tout votre compte.

Une fois l’autorisation terminée, vous êtes redirigé vers Apidog. La connexion au fournisseur est réutilisable pour les futurs projets.

Pour le détail du flux, y compris Azure DevOps via Git Connection, consultez la documentation du mode Spec-First.

Étape 2 : créez un projet depuis un dépôt et une branche

Indiquez maintenant à Apidog où se trouve la spécification OpenAPI.

1. Sélectionnez le dépôt contenant votre fichier OpenAPI.
2. Choisissez la branche à synchroniser, par exemple main.
3. Confirmez le chemin du fichier si Apidog le demande, par exemple :
   • openapi.yaml
   • docs/openapi.yaml
   • spec/openapi.yml
4. Créez le projet.

Apidog charge la spécification depuis cette branche. La barre latérale affiche vos endpoints et schémas, car le document est analysé comme un plan navigable.

À partir de ce moment, vous éditez la spécification du dépôt, pas une copie séparée.

Étape 3 : modifiez le YAML OpenAPI dans l’éditeur

Le mode Spec-First fournit un éditeur de type IDE pour le YAML OpenAPI, avec coloration syntaxique, validation en ligne et auto-complétion.

Exemple : ajoutez un endpoint de santé.

paths:
  /health:
    get:
      summary: Vérification de l'état du service
      operationId: getHealth
      responses:
        '200':
          description: Le service est opérationnel
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

Pendant l’édition :

• la nouvelle opération /health apparaît dans l’arborescence ;
• les erreurs YAML sont signalées en ligne ;
• les problèmes OpenAPI visibles, comme un bloc responses manquant ou un $ref incorrect, peuvent être corrigés avant le commit.

Cette approche réduit les erreurs découvertes tardivement dans une CI ou pendant la génération de documentation.

Pour approfondir la gestion des différences et de l’historique Git sur une spécification, consultez le guide sur le contrôle de version OpenAPI avec Git.

Étape 4 : commitez et poussez vers GitHub

Quand la modification est prête, poussez-la vers le dépôt.

1. Ouvrez le panneau Git ou contrôle de source du projet.
2. Vérifiez le diff affiché par Apidog.
3. Rédigez un message de commit clair, par exemple :

Ajouter le point d'extrémité /health

1. Cliquez sur Commiter et Pousser.

Apidog crée un commit sur la branche sélectionnée, puis le pousse vers le dépôt distant.

Vous pouvez ensuite ouvrir GitHub et vérifier :

• le commit dans l’historique de la branche ;
• l’auteur du commit ;
• le fichier OpenAPI modifié ;
• le diff correspondant.

Si vous changez d’avis avant de pousser, annulez les modifications non poussées. Tant que vous n’avez pas cliqué sur Commiter et Pousser, vos changements restent locaux.

Étape 5 : vérifiez l’état de synchronisation

Apidog affiche un indicateur de synchronisation pour montrer l’état entre l’éditeur et le dépôt distant.

Après un push réussi, l’indicateur affiche par exemple :

Synchronisé à l'instant

Cela confirme que la version locale et la branche distante contiennent le même document.

Si quelqu’un pousse une modification sur la même branche, Apidog la récupère dans le cadre de la synchronisation bidirectionnelle.

Si l’état indique une synchronisation en attente ou une version obsolète, récupérez les dernières modifications ou résolvez le conflit avant de continuer.

Dépannage

Les permissions Git échouent

Si un push échoue avec une erreur d’autorisation :

1. Vérifiez que vous avez accès en écriture au dépôt.
2. Vérifiez que vous avez accès à la branche ciblée.
3. Relancez l’autorisation OAuth depuis Apidog si le jeton a expiré ou a été révoqué.

La branche est protégée

Si main est protégée et exige des pull requests, le push direct peut être rejeté.

Dans ce cas :

• synchronisez une branche de travail ;
• poussez vos changements sur cette branche ;
• ouvrez une pull request depuis GitHub ou GitLab.

Un conflit de fusion apparaît

Un conflit peut se produire si quelqu’un a modifié la même partie du fichier OpenAPI pendant que vous travailliez.

Traitez-le comme un conflit Git classique :

1. récupérez la dernière version distante ;
2. comparez les sections YAML concernées ;
3. résolvez les conflits ;
4. validez le document ;
5. commitez à nouveau.

Comme OpenAPI est du texte brut, la résolution suit le même principe qu’un fichier de code.

La validation OpenAPI signale des erreurs

Apidog peut signaler des problèmes dans le YAML ou dans la structure OpenAPI.

Corrigez-les avant de pousser, surtout si la spécification alimente :

• la documentation ;
• les mocks ;
• les tests ;
• les SDK ;
• les validations en CI.

Une spécification valide réduit les erreurs en aval.

FAQ

La synchronisation avec GitHub fonctionne-t-elle aussi avec GitLab et Azure DevOps ?

Oui. Le mode Spec-First prend en charge GitHub et GitLab directement. Azure DevOps est pris en charge via Git Connection.

Le flux reste le même :

1. connecter le fournisseur ;
2. choisir le dépôt ;
3. choisir la branche ;
4. modifier la spécification ;
5. commiter ;
6. pousser.

Seul l’écran d’autorisation change selon le fournisseur.

Que se passe-t-il si un membre de l’équipe modifie la spécification pendant que je travaille dans Apidog ?

Apidog récupère les modifications depuis le dépôt dans le cadre de la synchronisation bidirectionnelle.

Si les modifications touchent des sections différentes du fichier, elles peuvent être fusionnées proprement. Si elles touchent les mêmes lignes ou les mêmes blocs YAML, vous résolvez un conflit Git standard.

Puis-je annuler une modification avant qu’elle n’atteigne GitHub ?

Oui. Tant que vous n’avez pas cliqué sur Commiter et Pousser, la modification reste locale.

Utilisez l’option permettant d’ignorer les modifications non poussées pour revenir au dernier état synchronisé. Rien ne sera envoyé au dépôt distant.