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

Votre spécification OpenAPI est le contrat entre votre API et ses consommateurs. Mais où réside ce contrat ?

Trop souvent, les spécifications d'API se trouvent dans des outils isolés—exportées une fois, oubliées, et rarement mises à jour lorsque l'implémentation change. La documentation dérive. Les collections de tests divergent. Les réviseurs approuvent les changements de code sans jamais voir les mises à jour correspondantes de la spécification.

Le Mode Spec-first inverse ce modèle. Vos fichiers OpenAPI ou Swagger deviennent la source de vérité, stockés directement dans votre dépôt Git à côté du code d'implémentation. Chaque changement de spécification passe par les mêmes branches, requêtes de tirage (pull requests) et processus de révision que vous utilisez déjà. La conception d'API, le test et la documentation restent tous synchronisés—automatiquement.

Dans ce tutoriel, je vais vous guider à travers la configuration d'un projet Spec-first dans Apidog, l'édition des spécifications avec votre équipe, et la synchronisation de tout avec votre flux de travail Git.

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

Dans un projet API typique, vous créez des points de terminaison via des formulaires visuels ou importez des spécifications existantes comme point de départ. L'outil stocke les définitions d'API en interne, et l'intégration Git (si disponible) est une étape d'exportation.

Le Mode Spec-first est différent. L'espace de travail principal est basé sur des fichiers :

• `openapi.yaml` ou `openapi.json` se trouvent dans votre dépôt
• Apidog analyse ces fichiers et génère une structure d'API navigable
• Vous modifiez les fichiers directement (ou via des formulaires pris en charge)
• Les changements sont automatiquement synchronisés avec Git

Le fichier de spécification fait toujours autorité. Apidog le lit, l'écrit et le maintient synchronisé avec votre dépôt.

Prérequis

Pour suivre, vous aurez besoin de :

• Un compte Apidog (le niveau gratuit fonctionne)
• Un dépôt Git avec un fichier OpenAPI/Swagger, ou un dépôt vide pour commencer à zéro
• Un accès en écriture au dépôt
• Une familiarité de base avec la syntaxe OpenAPI ou Swagger

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

Cliquez sur + Nouveau Projet dans Apidog et choisissez Mode Spec-first comme type de projet.

Ensuite, connectez votre fournisseur Git :

1. Sélectionnez votre fournisseur (GitHub, GitLab, Azure DevOps ou Bitbucket)
2. Choisissez une organisation ou un espace de travail
3. Sélectionnez un dépôt existant ou créez-en un nouveau
4. Sélectionnez la branche principale pour la synchronisation

Apidog se synchronisera avec la branche par défaut de votre dépôt. Si elle n'est pas nommée `main`, Apidog s'adapte automatiquement.

Étape 2 : Configurer la synchronisation par webhook (recommandé)

Lors de la configuration, vous verrez une option pour installer un webhook. Cela permet une synchronisation automatique chaque fois que votre équipe pousse des modifications vers 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 n'avez pas d'accès administrateur, ignorez cette étape—vous pouvez toujours synchroniser manuellement en utilisant Git Pull.

Avantages du webhook :

• L'équipe pousse des changements → Apidog se synchronise automatiquement
• Aucune actualisation manuelle nécessaire
• Tout le monde voit l'état le plus récent de la spécification

Si vous avez ignoré la configuration du webhook initialement, 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, votre projet ouvre l'espace de travail Spécifications—le hub central pour l'édition basée sur des fichiers et les opérations Git.

Trois panneaux fonctionnent ensemble :

Cliquez sur un point de terminaison dans l'arborescence de la structure → Apidog met en surbrillance la section correspondante dans votre fichier source. Naviguez de la vue API de haut niveau à la YAML de bas niveau sans changer d'onglet.

Étape 4 : Modifier vos fichiers de spécification

Vue Code : Édition directe

Pour la plupart des fichiers—YAML, JSON, Markdown—utilisez la vue Code pour éditer le texte brut.

Vos modifications restent dans le fichier. Apidog ne les transforme pas ni ne les stocke séparément. Le fichier de spécification reste la seule source de vérité.

Vue Formulaire : Édition structurée

Pour les nœuds OpenAPI pris en charge—points de terminaison, schémas, définitions et aperçu de l'API—passez à la vue Formulaire.

La vue Formulaire est utile lorsque :

• Vous ajoutez des points de terminaison avec tous les champs requis sans mémoriser la structure YAML
• Vous éditez des schémas visuellement
• Vous mettez à jour les définitions de sécurité et les métadonnées de l'API

Si un nœud ne prend pas en charge l'édition de formulaire, Apidog vous maintient en vue code.

Étape 5 : Valider et prévisualiser instantanément

Le Mode Spec-first inclut une validation en temps réel et un aperçu de la documentation—aucun outil externe n'est requis.

Vérifier les problèmes avec la validation

Cliquez sur Validation dans l'en-tête de l'éditeur. Un panneau affiche tous les avertissements et erreurs de votre spécification actuelle.

Le badge affiche le nombre total de problèmes. Il détecte :

• Les erreurs de syntaxe
• Les champs requis manquants
• Les violations de schéma
• Les problèmes de convention de nommage

Corrigez les problèmes avant de les valider (commit). Les réviseurs de votre équipe n'auront pas besoin de les repérer manuellement.

Prévisualiser votre documentation

Cliquez sur Prévisualiser pour voir comment votre spécification est rendue en tant que documentation API.

Pour les points de terminaison, la prévisualisation inclut deux onglets :

Pour les schémas et définitions, l'aperçu montre la vue de la documentation rendue.

La validation et la prévisualisation partagent le même panneau latéral. L'ouverture de l'un ferme automatiquement l'autre.

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

Lorsque des collaborateurs poussent des modifications vers votre dépôt, intégrez-les dans Apidog :

1. Ouvrez l'espace de travail Spécifications
2. Cliquez sur le nom de la branche actuelle dans la barre latérale
3. Sélectionnez Git Pull

Si la synchronisation par webhook est active, Apidog tire automatiquement les modifications lors des événements push du dépôt—aucune étape manuelle n'est nécessaire.

Étape 7 : Valider et pousser vos modifications

Après avoir édité des fichiers dans Apidog, renvoyez vos mises à jour vers Git :

1. Effectuez des modifications dans l'espace de travail Spécifications
2. Cliquez sur Changements dans la barre latérale pour voir les fichiers modifiés, ajoutés, renommés et supprimés
3. Cliquez sur Valider et Pousser
4. Sélectionnez les fichiers à inclure
5. Écrivez un message de validation
6. Cliquez sur Pousser

Vos mises à jour de spécifications apparaissent désormais dans le même flux de travail de requête de tirage (pull request) que vos modifications de code. Les coéquipiers peuvent examiner, commenter et approuver—l'implémentation et le contrat API au même endroit.

Conseil : Utilisez Annuler toutes les modifications si vous souhaitez abandonner les modifications locales avant de les pousser.

Étape 8 : Travailler avec des branches

Le Mode Spec-first prend en charge la collaboration complète basée sur les branches. Apidog mappe les branches Git aux branches de projet, vous permettant de basculer entre les versions de spécifications.

Opérations de branche courantes

La gestion des branches fonctionne comme vous l'attendez de Git—les branches de fonctionnalités, les versions et le développement parallèle se synchronisent tous correctement.

Étape 9 : Intégrer avec CI/CD

Étant donné que vos spécifications vivent dans Git, elles s'intègrent naturellement dans les pipelines d'automatisation :

• Linter les spécifications sur chaque PR en utilisant la validation Apidog ou des outils comme Spectral
• Générer la documentation automatiquement lorsque les spécifications fusionnent dans `main`
• Exécuter des tests API déclenchés par les changements de spécifications
• Synchroniser avec les systèmes en aval—passerelles API, serveurs mock, générateurs de SDK

Exemple de flux de travail 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

Vos spécifications API passent désormais par les mêmes contrôles qualité que votre code d'application.

Alternative : Projets basés sur le stockage interne

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

Ces projets utilisent le stockage interne d'Apidog mais offrent toujours :

• L'édition basée sur des fichiers
• La validation et la prévisualisation
• La gestion des branches

Les étiquettes de l'interface utilisateur s'ajustent légèrement :

• Git Pull devient Synchroniser
• Valider et Pousser devient Enregistrer

Migrez vers un Git externe dès que votre équipe est prête.

Résumé

Avec le Mode Spec-first, votre flux de travail API devient :

Le Mode Spec-first fait des fichiers OpenAPI le contrat qu'ils devraient être—versionnés, révisés et toujours alignés avec votre code.

Prêt à essayer ? Créez un projet Spec-first dans Apidog et connectez votre premier dépôt.