C'est quoi un workflow API Git-natif (et comment en créer un) ?

Votre code vit dans Git. Vos pipelines CI, vos revues et l’historique de vos versions vivent dans Git. Alors pourquoi votre spécification API vivrait-elle ailleurs ?

Essayez Apidog aujourd’hui

Un workflow API natif Git garde votre définition OpenAPI au même endroit que votre code. Vous modifiez la spécification comme un fichier YAML ou JSON, vous la commitez, puis vous la faites passer par le même processus de revue que le reste du projet. Pas de base cloud séparée. Pas d’export/import manuel. La spécification devient un fichier versionné dans votre dépôt.

💡 Apidog prend désormais en charge ce workflow avec le mode Spec-First. Vous concevez votre API dans un éditeur de style IDE, puis vous synchronisez les fichiers bruts en bidirectionnel avec GitHub ou GitLab. Ce guide explique le principe, les problèmes des spécifications bloquées dans le cloud, puis la configuration étape par étape.

Ce qu’est un workflow API natif Git

Un workflow API natif Git traite votre spécification API comme du code. Le fichier OpenAPI se trouve dans un dépôt, à côté de vos services. Chaque changement est un commit. Chaque commit a un auteur, un message et un diff.

Concrètement, vous obtenez les mêmes garanties que pour le code source :

• Historique des versions : vous voyez qui a modifié un endpoint et quand. git blame fonctionne aussi sur votre spécification.
• Branches et revues : les changements passent par des pull requests. Les reviewers inspectent le diff avant le merge.
• Source unique de vérité : le fichier dans main devient le contrat. Documentation, mocks, tests et générateurs lisent tous depuis ce fichier.

C’est le principe du workflow API spec-first : la spécification mène, l’implémentation suit. Pour approfondir cette approche, consultez le guide sur le développement API spec-first.

L’approche inverse consiste à stocker la spécification dans une application cloud propriétaire. Elle peut fonctionner au début, mais crée vite des frictions dès que l’équipe grandit ou que le processus de livraison devient plus strict.

Le problème des spécifications API bloquées dans le cloud

Beaucoup d’outils de conception API stockent la spécification dans leur propre base de données. Vous l’éditez via une interface. Le “fichier” que vous pensez manipuler est en réalité une donnée hébergée dans un système externe.

Les problèmes apparaissent vite.

1. La revue se fait à deux endroits

Le code est revu dans GitHub ou GitLab. La spécification est revue dans un autre outil, avec ses propres commentaires, statuts et historiques.

Résultat :

• les reviewers changent de contexte ;
• les validations ne sont pas synchronisées ;
• un changement API peut être approuvé côté design mais pas côté code, ou l’inverse.

2. Le diff est difficile à inspecter

Quand la spécification vit dans une base cloud, vous ne voyez pas toujours un diff ligne par ligne dans votre pull request. Vous approuvez une nouvelle version du design sans vérifier précisément ce qui a changé dans le contrat.

Avec un fichier OpenAPI dans Git, le diff est explicite :

 responses:
   "200":
     description: Order found
+  "404":
+    description: Order not found

3. L’export devient une étape fragile

Pour utiliser la spécification dans la CI, vous devez souvent :

1. exporter le fichier depuis l’outil ;
2. le commiter dans le dépôt ;
3. espérer que personne n’a modifié la version cloud entre-temps.

Vous avez alors deux sources de vérité : la version cloud et la version Git.

4. L’automatisation devient plus complexe

Les linters, tests de contrat et générateurs de code attendent généralement un fichier sur le disque.

Exemples :

npx @redocly/cli lint openapi.yaml

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client

Si la spécification est bloquée dans le cloud, vous devez ajouter une étape de récupération avant d’exécuter ces commandes.

Traiter votre spécification API comme du code supprime cette couche. Le fichier est la spécification. Git est l’historique. Votre pipeline fait le reste. Le principe est détaillé dans la spécification API en tant que code.

Comment fonctionne le mode Spec-First d’Apidog

Le mode Spec-First est conçu pour les équipes qui travaillent déjà avec des commits, des branches et des pull requests.

Vous éditez votre API sous forme de fichiers YAML ou JSON bruts. Apidog garde ces fichiers synchronisés avec votre dépôt Git dans les deux sens.

1. Éditer OpenAPI dans un éditeur de style IDE

Au lieu de remplir un formulaire, vous écrivez directement la spécification dans un éditeur de code.

L’éditeur fournit :

• la coloration syntaxique YAML et JSON ;
• la validation par rapport aux schémas OpenAPI et Swagger ;
• l’auto-complétion pour les mots-clés, types et références OpenAPI.

Vous gardez le contrôle du fichier réel. Pas de champs masqués. Pas de métadonnées réservées à l’interface.

2. Travailler avec des fichiers YAML/JSON bruts

Voici un exemple de fichier OpenAPI versionné dans Git :

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

C’est ce fichier qui arrive dans le dépôt. Ce que vous éditez est ce qui est commité.

3. Naviguer dans une arborescence générée automatiquement

Pendant l’édition, Apidog analyse la spécification et construit une arborescence dans la barre latérale gauche.

Vous pouvez naviguer rapidement entre :

• les chemins ;
• les opérations ;
• les schémas ;
• les composants.

C’est utile quand votre fichier OpenAPI contient plusieurs centaines ou milliers de lignes. Vous gardez la précision du fichier brut, tout en retrouvant la lisibilité d’un outil de conception.

4. Synchroniser Git dans les deux sens

Le mode Spec-First se connecte à votre fournisseur Git et synchronise les changements en bidirectionnel.

Il prend en charge :

• GitHub ;
• GitLab ;
• Azure DevOps via une connexion Git.

Le workflow est simple :

1. vous tirez les changements poussés par vos coéquipiers ;
2. vous éditez la spécification dans Apidog ;
3. vous commitez ;
4. vous poussez vers la branche suivie.

Le dépôt et l’espace de travail restent alignés.

5. Commit, push et statut de synchronisation

Vous pouvez gérer le cycle Git directement depuis Apidog :

• suivre les fichiers modifiés ;
• rédiger un message de commit ;
• pousser vers le dépôt distant ;
• vérifier l’état de synchronisation.

Après un push réussi, l’indicateur affiche un état du type “Synchronisé à l’instant”. Si vous changez d’avis avant le push, vous pouvez annuler les modifications non poussées et revenir à l’état synchronisé précédent.

Cette synchronisation bidirectionnelle est au cœur du workflow API natif Git. Pour une démonstration côté GitHub, consultez la synchronisation de la spécification OpenAPI vers GitHub.

Guide de configuration

Voici le cycle complet pour partir d’un dépôt et obtenir une spécification OpenAPI synchronisée. La référence complète est disponible dans la documentation du mode Spec-First.

Étape 1 — Créer un projet depuis un dépôt

Dans Apidog :

1. créez un nouveau projet Spec-First ;
2. connectez votre fournisseur Git ;
3. choisissez le dépôt qui contient votre spécification API ;
4. sélectionnez la branche à suivre, généralement main.

Apidog récupère les fichiers de spécification existants dans l’éditeur.

Étape 2 — Éditer la spécification

Ouvrez le fichier OpenAPI dans l’éditeur.

Vous pouvez par exemple :

• ajouter un endpoint ;
• modifier un schéma ;
• corriger une réponse ;
• ajouter un code d’erreur ;
• renommer une opération.

Exemple de changement typique :

responses:
  "200":
    description: Order found
  "404":
    description: Order not found

La coloration syntaxique, la validation et l’auto-complétion vous aident pendant l’écriture. L’arborescence se met à jour automatiquement.

Étape 3 — Vérifier les fichiers modifiés

Apidog indique les fichiers modifiés depuis la dernière synchronisation.

Vous pouvez identifier :

• les fichiers modifiés ;
• les fichiers ajoutés ;
• les fichiers supprimés.

Cela permet de vérifier exactement ce qui sera inclus dans le commit.

Étape 4 — Rédiger un message de commit

Écrivez un message clair, comme dans n’importe quel client Git.

Préférez :

Ajouter une réponse 404 à getOrder

Plutôt que :

Mettre à jour la spec

Un bon message de commit indique le changement fonctionnel, pas seulement le fait que le fichier a été modifié.

Étape 5 — Pousser vers Git

Poussez le commit vers la branche suivie.

Vos coéquipiers, votre pipeline CI et vos outils de documentation voient maintenant la nouvelle version de la spécification.

Étape 6 — Vérifier l’état “Synchronisé à l’instant”

Après le push, vérifiez l’indicateur de synchronisation.

Quand il affiche “Synchronisé à l’instant”, cela signifie que vos changements locaux et la branche distante correspondent.

À partir de là, le changement suit votre processus habituel :

1. pull request ;
2. revue ;
3. validation CI ;
4. merge.

La boucle complète devient donc :

pull → éditer → commit → push → vérifier

Pas d’export manuel. Pas de deuxième source de vérité.

Mode Spec-First vs mode Design-First

Apidog prend en charge deux façons de travailler. La différence principale concerne l’emplacement de la spécification et la manière de l’éditer.

Critère	Mode Spec-First (bêta)	Mode Design-First
Stockage des spécifications	Fichiers YAML/JSON bruts dans Git	Projet cloud Apidog
Éditeur principal	Éditeur de code de style IDE	Interface visuelle basée sur des formulaires
Contrôle de version	Git natif : commits, branches, diffs	Historique et branches Apidog
Synchronisation Git bidirectionnelle	Oui : GitHub, GitLab, Azure DevOps	Via export/import
Idéal pour	Équipes qui vivent dans Git	Équipes qui préfèrent un workflow visuel

Aucun mode n’est universellement meilleur. Ils répondent à des habitudes différentes.

Choisissez Spec-First si votre processus de revue et de publication fonctionne déjà avec Git. Choisissez Design-First si votre équipe préfère concevoir visuellement et manipule rarement l’OpenAPI brut.

Quand utiliser le mode Spec-First

Utilisez le mode Spec-First si :

• votre spécification doit passer par des pull requests ;
• vous voulez un vrai historique de commits sur votre contrat API ;
• vous voulez utiliser git blame sur les endpoints et schémas ;
• votre CI exécute des linters OpenAPI ;
• votre pipeline lance des tests de contrat ;
• vous générez du code depuis la spécification ;
• plusieurs ingénieurs éditent le contrat API ;
• vous voulez des diffs propres et fusionnables ;
• vous voulez arrêter les exports manuels entre outils.

Exemple de pipeline CI typique :

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  lint-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI spec
        run: npx @redocly/cli lint openapi.yaml

Dans ce type de workflow, la spécification doit être disponible directement dans le dépôt. C’est exactement le cas avec une approche native Git.

Quand rester sur une approche visuelle

Une approche visuelle et cloud-first peut rester pertinente si :

• votre équipe conçoit des API sans écrire d’OpenAPI brut ;
• des profils non-ingénieurs sont propriétaires de la spécification ;
• vous préférez un éditeur basé sur des formulaires ;
• votre processus de validation ne dépend pas fortement de Git.

FAQ

Qu’est-ce qu’un workflow API natif Git ?

Un workflow API natif Git stocke votre spécification OpenAPI comme un fichier dans un dépôt Git. Chaque modification passe par des commits, branches et pull requests. La spécification suit donc le même processus de revue et de versioning que le code applicatif.

Le mode Spec-First d’Apidog prend-il en charge GitHub et GitLab ?

Oui. Le mode Spec-First se synchronise directement avec GitHub et GitLab en bidirectionnel. Azure DevOps est pris en charge via une connexion Git. Vous connectez le dépôt, choisissez une branche, puis Apidog garde les changements locaux et distants synchronisés.

Puis-je éditer des fichiers OpenAPI en YAML ou JSON bruts ?

Oui. Le mode Spec-First fournit un éditeur de style IDE pour YAML et JSON bruts, avec coloration syntaxique, validation de schéma et auto-complétion pour OpenAPI et Swagger. Une arborescence analyse aussi le fichier pour faciliter la navigation.

Quelle est la différence entre le mode Spec-First et le mode Design-First ?

Le mode Spec-First conserve la spécification sous forme de fichiers dans Git et l’édite dans un éditeur de code avec synchronisation bidirectionnelle. Le mode Design-First conserve la spécification dans un projet cloud Apidog avec un éditeur visuel basé sur des formulaires.

Choisissez Spec-First si votre workflow fonctionne déjà avec Git.

Conclusion

Un workflow API natif Git rapproche votre contrat API de votre code. La spécification devient un fichier, le fichier devient un commit, et le commit passe par le même processus de revue que le reste du projet.

Le mode Spec-First d’Apidog fournit l’éditeur de style IDE, l’arborescence navigable et la synchronisation Git bidirectionnelle pour mettre ce workflow en place. Vous éditez du YAML ou du JSON brut, vous commitez un message clair, vous poussez, puis vous vérifiez que l’état affiche “Synchronisé à l’instant”.

Essayez le mode Spec-First et ramenez votre spécification API dans Git.