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

Si votre document OpenAPI se trouve dans un dépôt Git mais que vous le modifiez à l'intérieur d'un client API, vous connaissez déjà les frictions : copier le YAML, le coller, espérer que personne d'autre n'a touché le fichier, et prier que l'importation n'ait pas discrètement supprimé un champ. Maintenir une spécification et un dépôt en accord manuellement est le genre de corvée qui se brise précisément quand vous êtes pressé.

Ce guide vous montre comment synchroniser votre spécification OpenAPI avec GitHub en utilisant le mode Spec-First d'Apidog, afin que la spécification dans votre dépôt et la spécification dans votre éditeur restent la même chose au lieu de deux copies que vous conciliez constamment. Nous allons connecter un fournisseur, ouvrir un projet directement depuis un dépôt, modifier le YAML et repousser le changement vers GitHub en une seule fois. Les mêmes étapes fonctionnent pour GitLab.

Passons aux choses sérieuses.

Ce que signifie réellement la synchronisation bidirectionnelle

La synchronisation bidirectionnelle signifie que les modifications circulent dans les deux sens, automatiquement, sans étape d'exportation intermédiaire.

• Apidog vers Git : Lorsque vous modifiez le document OpenAPI dans Apidog et que vous effectuez un commit, la modification est poussée vers votre dépôt en tant que commit Git normal sur la branche que vous avez choisie.
• Git vers Apidog : Lorsqu'un membre de l'équipe (ou vous, depuis votre IDE) pousse une modification sur cette branche, Apidog la récupère afin que votre éditeur reflète ce qui se trouve réellement dans le dépôt.

Le dépôt est la source unique de vérité. Apidog est un éditeur riche qui s'y superpose. C'est toute l'idée derrière un workflow API Git-native : la spécification est versionnée, révisée et son historique est suivi comme n'importe quel autre fichier de votre base de code, au lieu de se trouver dans un outil qui exporte périodiquement un instantané.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Apidog installé (application de bureau ou web), et connecté.
• Un dépôt GitHub ou GitLab qui contient déjà un document OpenAPI, ou un dépôt pour lequel vous avez un accès en écriture. Azure DevOps est également pris en charge via Git Connection.
• Le mode Spec-First (bêta) activé. C'est le mode qui transforme votre projet en une couche mince au-dessus d'un dépôt Git plutôt que le propre stockage d'Apidog.

Vous aurez besoin d'une permission d'écriture sur la branche que vous comptez synchroniser. Un accès en lecture seule vous permet de récupérer mais pas de pousser.

Étape 1 : Connectez votre fournisseur Git

Tout d'abord, autorisez Apidog à communiquer avec votre fournisseur.

1. Ouvrez Apidog et créez un nouveau projet, en choisissant le mode Spec-First.
2. Lorsque vous êtes invité à choisir une source, sélectionnez votre fournisseur, GitHub ou GitLab.
3. Cliquez sur Autoriser. Votre navigateur ouvre l'écran OAuth du fournisseur.
4. Accordez à Apidog l'accès aux dépôts que vous souhaitez synchroniser. Sur GitHub, vous pouvez limiter cela à des dépôts spécifiques plutôt qu'à l'ensemble de votre compte.

Une fois l'autorisation terminée, vous êtes redirigé vers Apidog, le fournisseur étant connecté. Vous ne faites cela qu'une seule fois par fournisseur, les futurs projets réutiliseront la connexion.

Pour la référence complète sur ce flux, y compris Azure DevOps via Git Connection, consultez la documentation du mode Spec-First.

Étape 2 : Créez un projet à partir d'un dépôt et d'une branche

Maintenant, indiquez à Apidog la spécification réelle.

1. Le fournisseur étant connecté, choisissez le dépôt qui contient votre fichier OpenAPI.
2. Choisissez la branche sur laquelle synchroniser, généralement main. C'est la branche sur laquelle vos commits atterriront et la branche qu'Apidog surveille pour les changements entrants.
3. Confirmez le chemin vers le document OpenAPI si Apidog le demande (par exemple openapi.yaml à la racine du dépôt, ou sous docs/).
4. Créez le projet.

Apidog clone la spécification de cette branche et l'ouvre. La barre latérale gauche se remplit avec vos points d'extrémité et vos schémas, car Apidog a analysé le document en un plan navigable. Vous consultez maintenant la spécification du dépôt, en direct.

Étape 3 : Modifiez votre YAML OpenAPI dans l'éditeur de code

Le mode Spec-First vous offre un éditeur de style IDE pour le YAML OpenAPI brut, avec coloration syntaxique, validation en ligne et auto-complétion. Vous écrivez directement l'OpenAPI ; Apidog maintient le plan visuel à jour pendant que vous tapez.

Ajoutons un petit point d'extrémité. Supposons que vous souhaitiez une vérification 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 que vous tapez, deux choses se produisent. La barre latérale gauche analyse automatiquement le plan, de sorte que votre nouvelle opération /health apparaît immédiatement dans l'arborescence. Et le validateur signale les problèmes en ligne, un bloc responses manquant, un mauvais $ref, une erreur d'indentation, avant même que vous ne commitiez. Si le YAML est mal formé, vous le verrez souligné plutôt que de le découvrir plus tard dans un pipeline échoué.

C'est aussi là que le contrôle de version prend tout son sens. Si vous souhaitez examiner plus en détail la manière dont les différences et l'historique se manifestent sur une spécification, le guide sur le contrôle de version OpenAPI avec Git l'explique en détail.

Étape 4 : Commitez et poussez

Lorsque la modification semble correcte, envoyez-la à GitHub.

1. Ouvrez le panneau de commit (la zone Git/contrôle de source du projet).
2. Vérifiez la modification. Apidog montre ce qui a été modifié par rapport à la version synchronisée.
3. Rédigez un message de commit, traitez-le comme n'importe quel commit : Ajouter le point d'extrémité /health.
4. Cliquez sur Commiter et Pousser.

Apidog commite sur votre branche choisie et pousse vers le dépôt distant. Ouvrez votre dépôt sur GitHub et vous verrez le commit dans l'historique de la branche, avec l'auteur attendu, touchant exactement le fichier OpenAPI.

Vous avez changé d'avis avant de pousser ? Vous pouvez annuler les modifications non poussées pour restaurer le document à son dernier état synchronisé. Rien ne quitte Apidog tant que vous n'avez pas commité, donc les expériences locales restent locales.

Étape 5 : Vérifiez l'état de la synchronisation

Apidog affiche un indicateur de synchronisation pour que vous sachiez toujours où vous en êtes.

Après une poussée réussie, l'indicateur affiche "Synchronisé à l'instant". C'est la confirmation que l'éditeur et la branche distante contiennent le même document. Avec le temps, il se met à jour ("Synchronisé il y a 5 minutes") et, lorsque quelqu'un d'autre pousse, Apidog récupère le changement et réinitialise l'indicateur après réconciliation.

Si l'indicateur montre un état en attente ou obsolète, cela signifie que la copie locale et le dépôt distant ont divergé, c'est votre signal de récupérer ou de résoudre avant de continuer.

Dépannage

Quelques éléments ont tendance à dérouter les gens la première fois.

• Autorisation expirée ou révoquée. Si les poussées commencent à échouer avec une erreur de permission, réexécutez l'autorisation à partir de l'étape 1. Les jetons peuvent être révoqués côté fournisseur ou simplement expirer.
• Mauvaise branche. Pousser vers une branche main protégée qui nécessite des pull requests sera rejeté. Synchronisez soit avec une branche de travail, soit ajustez les règles de protection de la branche. Vérifiez bien que la branche choisie à l'étape 2 correspond à l'endroit où vous vous attendez à ce que les commits atterrissent.
• Conflits de fusion. Si un membre de l'équipe a poussé sur la même branche pendant que vous modifiiez, le dépôt distant a avancé par rapport à votre copie locale. Récupérez les dernières modifications, réconciliez le YAML qui se chevauche et commitez à nouveau. Parce que la spécification est du texte brut, les conflits se résolvent de la même manière que n'importe quel conflit de code.
• Les erreurs de validation bloquent votre flux. Apidog ne vous empêchera pas de commiter du YAML invalide, mais vous devriez d'abord corriger ce que le validateur en ligne signale. Une spécification propre maintient l'intégrité de vos documents générés, de vos maquettes et de vos tests.

FAQ

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

Oui. Le mode Spec-First prend en charge GitHub et GitLab directement, et Azure DevOps via Git Connection. Le flux de connexion-édition-commit-push est le même pour les trois ; seul l'écran d'autorisation diffère selon le fournisseur.

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

Apidog récupère leur modification dans votre éditeur dans le cadre de la synchronisation bidirectionnelle. Si vos modifications et les leurs touchent des parties différentes du fichier, elles fusionnent proprement. Si elles se chevauchent, vous résoudrez un conflit Git standard, comme vous le feriez dans n'importe quel fichier texte.

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

Oui. Tant que vous n'avez pas cliqué sur Commiter et Pousser, vos modifications sont locales. Utilisez l'option "ignorer les modifications non poussées" pour rétablir le document à son dernier état synchronisé, et rien n'atteindra le dépôt distant.