Antoine Laurent

Posted on Jun 10 • Originally published at apidog.com

Collaboration native Git pour les tests et l'ingénierie API

Votre spécification OpenAPI est le contrat entre votre API et ses consommateurs. La première décision d’architecture consiste donc à choisir où ce contrat vit, comment il est versionné, et comment votre équipe le relit.

Essayez Apidog aujourd’hui

Trop souvent, les spécifications d’API sont stockées dans des outils isolés : exportées une fois, oubliées, puis désynchronisées dès que l’implémentation évolue. Résultat : la documentation dérive, les collections de tests divergent, et les reviewers valident du code sans voir les changements de contrat associés.

Le Mode Spec-first inverse ce modèle. Vos fichiers OpenAPI ou Swagger deviennent la source de vérité, stockés dans votre dépôt Git à côté du code. Chaque changement de spécification passe par les mêmes branches, pull requests et revues que le reste du projet. La conception d’API, le test et la documentation restent synchronisés.

Dans ce tutoriel, vous allez configurer un projet Spec-first dans Apidog, modifier vos fichiers OpenAPI avec votre équipe, puis synchroniser le tout avec votre workflow Git.

Qu’est-ce que le Mode Spec-first ?

Dans un projet API classique, vous créez des endpoints dans une interface visuelle ou vous importez une spécification existante. L’outil stocke ensuite les définitions d’API en interne, et Git n’intervient souvent qu’au moment d’un export.

Le Mode Spec-first fonctionne autrement :

openapi.yaml ou openapi.json reste dans votre dépôt Git
Apidog analyse ces fichiers et génère une structure API navigable
vous modifiez les fichiers directement, en YAML/JSON ou via une vue formulaire quand elle est disponible
les changements sont synchronisés avec Git

Le fichier de spécification fait toujours autorité. Apidog le lit, l’écrit et le garde aligné avec votre dépôt.

Prérequis

Avant de commencer, préparez :

un compte Apidog, le plan gratuit suffit
un dépôt Git contenant déjà un fichier OpenAPI/Swagger, ou un dépôt vide
un accès en écriture au dépôt
une connaissance de base de la syntaxe OpenAPI ou Swagger

Exemple minimal de fichier openapi.yaml :

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /health:
    get:
      summary: Vérifier l’état de l’API
      responses:
        "200":
          description: OK

Étape 1 : Créer un projet Spec-first

Dans Apidog :

Cliquez sur + Nouveau Projet
Sélectionnez Mode Spec-first
Connectez votre fournisseur Git
Sélectionnez votre dépôt
Choisissez la branche principale utilisée pour la synchronisation

Fournisseurs Git pris en charge :

GitHub
GitLab
Azure DevOps
Bitbucket

Apidog se synchronise avec la branche par défaut du dépôt. Si elle ne s’appelle pas main, Apidog utilise automatiquement le nom réel de votre branche principale.

Étape 2 : Configurer la synchronisation par webhook

Pendant la configuration, Apidog propose d’installer un webhook. Activez-le si possible : il permet de synchroniser automatiquement le projet dès qu’un membre de l’équipe pousse des changements dans le dépôt.

Note : l’installation du webhook nécessite généralement une autorisation d’administrateur sur le dépôt. Si vous ne l’avez pas, ignorez cette étape et utilisez Git Pull manuellement depuis Apidog.

Avantages du webhook :

un git push déclenche la synchronisation Apidog
l’équipe voit la dernière version de la spécification
moins de risques de travailler sur une version obsolète

Si vous avez ignoré cette étape, vous pouvez l’ajouter plus tard depuis :

Paramètres du projet > Git & Branches

Étape 3 : Explorer l’espace de travail des spécifications

Après la création du projet, Apidog ouvre l’espace de travail Spécifications. C’est l’endroit où vous éditez les fichiers, naviguez dans la structure API et lancez les opérations Git.

L’interface est organisée en trois zones :

Panneau	Utilité
Explorateur de fichiers	Affiche les fichiers et dossiers du dépôt synchronisé
Arborescence de la structure API	Affiche les endpoints, schémas, définitions et aperçu générés depuis OpenAPI
Éditeur	Permet de modifier les fichiers en vue code ou en vue formulaire

Workflow pratique :

Cliquez sur un endpoint dans l’arborescence API
Apidog ouvre la section correspondante dans le fichier source
Modifiez le YAML/JSON
Validez la spécification
Commitez et poussez les changements

Vous pouvez donc passer de la vue API de haut niveau au fichier OpenAPI sans changer d’outil.

Étape 4 : Modifier vos fichiers de spécification

Vue Code : édition directe

Pour les fichiers YAML, JSON ou Markdown, utilisez la vue Code.

Exemple : ajouter un endpoint GET /users/{id} dans openapi.yaml.

paths:
  /users/{id}:
    get:
      summary: Récupérer un utilisateur par ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Utilisateur trouvé
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Utilisateur introuvable

Puis ajoutez le schéma associé :

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email

Apidog ne déplace pas ces données dans un stockage propriétaire : le fichier reste la source de vérité.

Vue Formulaire : édition structurée

Pour certains nœuds OpenAPI, vous pouvez passer en vue Formulaire.

Utilisez cette vue pour :

créer un endpoint sans mémoriser toute la structure YAML
modifier visuellement des schémas
mettre à jour les métadonnées de l’API
configurer des définitions de sécurité

Si le nœud sélectionné ne prend pas en charge l’édition via formulaire, Apidog reste en vue Code.

Étape 5 : Valider et prévisualiser la spécification

Le Mode Spec-first inclut une validation en temps réel et un aperçu de la documentation.

Vérifier les erreurs avec la validation

Cliquez sur Validation dans l’en-tête de l’éditeur.

Le panneau liste les erreurs et avertissements détectés dans la spécification, par exemple :

erreurs de syntaxe YAML ou JSON
champs OpenAPI obligatoires manquants
violations de schéma
problèmes de convention de nommage

Corrigez ces problèmes avant de créer une pull request. Cela évite de demander aux reviewers de repérer manuellement des erreurs de contrat.

Prévisualiser la documentation

Cliquez sur Prévisualiser pour voir le rendu de la documentation générée depuis la spécification.

Pour les endpoints, la prévisualisation contient deux onglets :

Onglet	Contenu
Docs	Documentation générée de l’endpoint
Essayer	Panneau de requête en direct basé sur la définition de l’endpoint

Pour les schémas et définitions, l’aperçu affiche la documentation rendue.

La validation et la prévisualisation utilisent le même panneau latéral. Ouvrir l’un ferme automatiquement l’autre.

Étape 6 : Récupérer les mises à jour de votre équipe

Quand un collègue pousse des modifications dans le dépôt, récupérez-les dans Apidog :

Ouvrez l’espace de travail Spécifications
Cliquez sur le nom de la branche actuelle dans la barre latérale
Sélectionnez Git Pull

Si le webhook est actif, Apidog récupère automatiquement les changements lors des événements push.

Bon réflexe en équipe : faites un Git Pull avant de modifier une spécification, surtout si plusieurs personnes travaillent sur les mêmes fichiers OpenAPI.

Étape 7 : Valider et pousser vos modifications

Après modification, renvoyez vos changements vers Git :

Ouvrez Changements dans la barre latérale
Vérifiez les fichiers modifiés, ajoutés, renommés ou supprimés
Cliquez sur Valider et Pousser
Sélectionnez les fichiers à inclure
Écrivez un message de commit clair
Cliquez sur Pousser

Exemples de messages de commit utiles :

docs(api): add GET /users/{id} endpoint

feat(spec): add User schema required fields

fix(openapi): correct response schema for 404 errors

Vos changements de spécification apparaissent ensuite dans le même workflow de pull request que vos changements de code. Les reviewers peuvent vérifier l’implémentation et le contrat API au même endroit.

Conseil : utilisez Annuler toutes les modifications si vous voulez abandonner les changements locaux avant de les pousser.

Étape 8 : Travailler avec des branches

Le Mode Spec-first prend en charge la collaboration basée sur les branches. Apidog mappe les branches Git aux branches de projet pour vous permettre de travailler sur plusieurs versions de spécification.

Opérations courantes :

Action	Comment faire
Changer de branche	Cliquez sur le nom de la branche, puis sélectionnez une autre branche
Importer une branche Git existante	Cliquez sur Importer une nouvelle branche, sélectionnez la branche, puis importez-la
Créer une nouvelle branche	Allez dans Paramètres du projet > Git & Branches, puis cliquez sur Nouvelle branche
Corriger les problèmes de synchronisation	Utilisez Re-synchroniser dans les paramètres de la branche
Afficher les journaux de synchronisation	Ouvrez les actions de la branche, puis cliquez sur Afficher les journaux

Exemple de workflow :

main
└── feature/add-user-endpoints
    ├── openapi.yaml
    └── docs/

Créez une branche feature/add-user-endpoints
Ajoutez les endpoints et schémas dans openapi.yaml
Validez la spécification dans Apidog
Poussez la branche
Ouvrez une pull request
Faites relire le code et la spec ensemble

Étape 9 : Intégrer la spécification dans CI/CD

Comme vos fichiers OpenAPI vivent dans Git, vous pouvez les intégrer à vos pipelines :

linter la spécification sur chaque pull request
générer la documentation après merge dans main
exécuter des tests API déclenchés par un changement de spec
synchroniser avec des systèmes en aval : passerelles API, serveurs mock, générateurs de SDK

Exemple de workflow GitHub Actions :

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

Avec ce type de pipeline, la spécification API passe par les mêmes contrôles qualité que le code applicatif.

Alternative : projets basés sur le stockage interne

Si vous n’êtes pas encore prêt à connecter un dépôt Git externe, Apidog propose aussi des projets Spec-first basés sur le stockage interne.

Ces projets conservent :

l’édition basée sur des fichiers
la validation
la prévisualisation
la gestion des branches

Les libellés changent légèrement :

Projet Git externe	Projet avec stockage interne
Git Pull	Synchroniser
Valider et Pousser	Enregistrer

Vous pouvez commencer avec le stockage interne, puis migrer vers un dépôt Git externe quand votre équipe est prête.

Résumé

Avec le Mode Spec-first, votre workflow API devient plus proche d’un workflow de développement standard :

Avant Spec-first	Après Spec-first
Les spécifications vivent dans un outil séparé	Les spécifications vivent dans votre dépôt Git
Synchronisation par export/import	Synchronisation via Git et webhook
Revue de spec séparée de la revue de code	Revue dans les pull requests
Documentation générée à part	Aperçu pendant l’édition
Tests déconnectés de la spec	Tests déclenchés par les changements de spec

Le Mode Spec-first transforme vos fichiers OpenAPI en vrai contrat versionné : lisible, relu, testé et aligné avec le code.

Pour l’adopter, commencez simplement :

Placez votre openapi.yaml dans Git
Créez un projet Spec-first dans Apidog
Connectez votre dépôt
Activez le webhook si possible
Faites passer les changements de contrat par pull request

DEV Community