Mode Spec-First d'Apidog : L'ère du Design Visuel Unique est Révolue

Il y a deux façons courantes de gérer une spécification OpenAPI dans une équipe API.

Essayez Apidog aujourd’hui

La première consiste à écrire le fichier OpenAPI à la main, à le commiter dans un répertoire specs/, puis à traiter Git comme la source de vérité. La seconde consiste à utiliser un concepteur visuel, exporter la spécification quand la CI échoue, puis corriger la dérive entre l’interface et le dépôt.

J’ai travaillé avec les deux approches. La première demande plus d’effort au départ, mais elle devient plus fiable avec le temps. La seconde est plus rapide le premier jour, mais elle peut créer de la dette si la spécification générée n’est pas synchronisée avec Git.

Avec le Mode Spec-First (Bêta), Apidog ajoute une option utile pour les équipes qui veulent garder OpenAPI dans Git tout en bénéficiant d’un environnement de conception API.

Ce que le Mode Spec-First change

Apidog propose maintenant deux modes de projet.

Le mode classique fonctionne comme un concepteur visuel : vous créez des dossiers, des endpoints et des schémas via des formulaires. La spécification OpenAPI est générée en arrière-plan.

Le Mode Spec-First inverse ce modèle :

• vous éditez directement des fichiers .yaml ou .json ;
• la spécification OpenAPI reste l’artefact principal ;
• le dépôt Git devient la source de vérité ;
• Apidog affiche une vue navigable des endpoints générée depuis le fichier ;
• les modifications peuvent être synchronisées dans les deux sens avec Git.

Autrement dit, l’interface ne remplace pas le fichier OpenAPI. Elle devient une couche de navigation, d’édition et de synchronisation autour de ce fichier.

Le point important : vous gardez le workflow spec-first sans perdre la navigation visuelle. Vous écrivez la spécification, et Apidog construit automatiquement l’arborescence des routes à partir du contenu du fichier.

Configuration pas à pas

Voici le flux de configuration complet.

1. Créer un projet en Mode Spec-First

Depuis l’écran des projets :

+ Nouveau Projet → Général → Mode Spec-first

Le Mode Général est marqué comme recommandé, donc le Mode Spec-first peut être facile à manquer. Sélectionnez explicitement la tuile Mode Spec-first.

2. Connecter le dépôt Git

Dans la même boîte de dialogue, allez dans :

Se connecter avec le dépôt Git

Puis sélectionnez :

• l’organisation ;
• le dépôt ;
• la branche principale.

Dans mon cas, j’ai utilisé GitHub. Une fois l’accès autorisé, Apidog synchronise les fichiers de spécification depuis cette branche.

3. Créer le projet

Renseignez ensuite :

• le nom du projet ;
• les permissions d’équipe ;
• les paramètres d’accès nécessaires.

Cliquez sur Créer.

Apidog importe alors les fichiers .yaml et .json présents dans le dépôt.

Éditer la spécification OpenAPI

Une fois le projet créé, ouvrez un fichier YAML.

Vous obtenez un éditeur de code avec :

• coloration syntaxique ;
• autocomplétion basée sur le schéma OpenAPI ;
• aperçu des endpoints dans la barre latérale ;
• navigation directe vers la définition d’une route.

Par exemple, si vous ajoutez un endpoint dans paths, il apparaît dans l’arborescence générée :

paths:
  /store/token:
    post:
      summary: Générer un token
      operationId: createStoreToken
      responses:
        "200":
          description: Token généré

L’intérêt est pratique : vous n’avez pas besoin de parcourir tout le YAML pour retrouver une route. Vous pouvez continuer à travailler dans le fichier, tout en utilisant la vue latérale comme table des matières.

Commiter et pousser les changements

Quand la modification est prête :

Commit & Push

La boîte de dialogue affiche :

• les fichiers modifiés ;
• un champ de message de commit ;
• un bouton Pousser ;
• une option pour annuler toutes les modifications.

Il n’y a pas d’étape de staging séparée. Les fichiers listés dans Modifications partiront dans le commit.

Exemple de message utile :

Add store token endpoint to OpenAPI spec

Surveiller l’état de synchronisation

Regardez l’indicateur en bas à gauche de l’espace de travail.

Il indique si votre copie locale est :

• synchronisée avec le dépôt ;
• en retard ;
• en avance ;
• désynchronisée.

Dans un workflow spec-first, cet indicateur devient important. Si la spécification est utilisée par la CI, par un générateur de SDK ou par une documentation publique, vous devez savoir rapidement si le fichier dans Apidog correspond bien au fichier dans Git.

Ce que j’ai constaté en pratique

L’aperçu se met à jour rapidement

L’arborescence des endpoints se met à jour pendant l’édition. C’est utile lorsque vous ajoutez ou déplacez des routes dans un fichier OpenAPI volumineux.

Au lieu de traiter la vue latérale comme un simple rapport après sauvegarde, vous pouvez l’utiliser comme outil de navigation en continu.

La synchronisation Git fonctionne dans les deux sens

J’ai aussi modifié le même fichier depuis mon clone local, puis poussé depuis le terminal.

Apidog a détecté que le dépôt distant avait changé. Après synchronisation, les modifications sont apparues dans l’éditeur.

Cela permet de conserver plusieurs styles de travail dans la même équipe :

• certains peuvent éditer avec Vim ou VS Code ;
• d’autres peuvent utiliser Apidog ;
• le fichier Git reste la référence commune.

Le mode ne se change pas après création

Un point important : un projet créé en Mode Spec-First reste un projet Spec-First.

Vous ne pouvez pas basculer ensuite vers le concepteur visuel dans le même projet, car les modèles sous-jacents sont différents.

Si votre équipe veut utiliser les deux approches, le workflow le plus simple est :

1. garder la spécification OpenAPI dans un dépôt Git ;
2. connecter un projet Spec-First à ce dépôt ;
3. utiliser un projet séparé pour les personnes qui travaillent plutôt en mode visuel.

Ce n’est pas un flux parfait, mais il permet de conserver Git comme source de vérité.

Quand utiliser le Mode Spec-First

Le Mode Spec-First convient si :

• vous écrivez déjà vos fichiers OpenAPI à la main ;
• votre CI exécute des validations comme spectral lint ;
• vous générez des SDK à partir de la spécification ;
• vous voulez que la spécification reste dans Git ;
• vous avez déjà une étape d’export manuel qui crée de la dérive ;
• votre équipe veut un outil visuel sans abandonner le fichier YAML.

Exemple de workflow typique :

Modifier OpenAPI dans Apidog
→ Commit & Push
→ CI : spectral lint
→ Génération SDK / documentation / mocks
→ Review via pull request

Dans ce type d’organisation, Apidog devient un éditeur OpenAPI connecté au dépôt, plutôt qu’un système séparé à synchroniser manuellement.

Quand éviter ce mode

Le Mode Spec-First est moins adapté si :

• votre équipe ne connaît pas encore OpenAPI ;
• le concepteur visuel est indispensable pour contribuer ;
• vos contributeurs ne veulent pas manipuler YAML ou JSON ;
• vous avez besoin de mélanger les deux modes dans un seul projet.

Dans ce cas, le mode par défaut d’Apidog reste plus accessible.

Le Mode Spec-First privilégie la fidélité au fichier et au dépôt Git. Ce n’est pas toujours le bon compromis pour une équipe qui découvre encore la conception d’API.

À retenir

Le principal intérêt du Mode Spec-First est simple : le fichier OpenAPI dans le dépôt est le même fichier que celui édité dans Apidog.

Il n’y a plus besoin de considérer l’export comme une étape séparée. Git reste la source de vérité, tandis qu’Apidog fournit :

• un éditeur de spécification ;
• une navigation visuelle ;
• l’autocomplétion OpenAPI ;
• la synchronisation Git ;
• un aperçu exploitable des endpoints.

Si votre équipe travaille déjà en spec-first, ce mode mérite un essai. Créez un projet en Mode Spec-First, connectez un dépôt existant, modifiez un fichier YAML, puis poussez un premier commit. Vous saurez rapidement si ce workflow remplace avantageusement votre combinaison actuelle d’éditeur, scripts d’export et vérifications manuelles.