Spec-First ou Design-First: Quel Mode Apidog Choisir ?

Le module APIs d'Apidog propose deux façons de construire le même artefact : un contrat API. Vous pouvez le concevoir avec des formulaires visuels ou l’écrire directement dans un éditeur de spécification synchronisé avec Git. Dans les deux cas, vous obtenez une spécification OpenAPI valide. Le bon choix dépend surtout de votre workflow d’équipe.

Essayez Apidog aujourd’hui

Ce guide vous aide à choisir entre le mode Design-First et le mode Spec-First dans Apidog : fonctionnement, gestion de Git, cas d’usage, et étapes pour basculer d’un mode à l’autre. Le changement se fait via un bouton en bas à gauche du module APIs, donc le choix n’est pas définitif.

Les deux approches

Dans les deux modes, le principe reste le même : vous définissez le contrat API avant d’écrire l’implémentation.

Ce contrat devient la source de vérité pour :

• la documentation ;
• les mocks ;
• les tests ;
• les schémas de requête et de réponse ;
• l’implémentation côté backend.

La différence se situe dans la manière de rédiger ce contrat.

Design-First

En mode Design-First, vous créez votre API via une interface structurée :

• méthode HTTP ;
• chemin ;
• paramètres de requête ou de chemin ;
• body de requête ;
• schémas de réponse ;
• exemples ;
• composants réutilisables.

Apidog génère l’OpenAPI en arrière-plan.

Spec-First

En mode Spec-First, vous écrivez directement la spécification OpenAPI ou Swagger en YAML ou JSON.

Exemple simplifié :

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Récupérer un utilisateur
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Utilisateur trouvé

Ici, la spécification est traitée comme du code source : versionnée, relue, validée et synchronisée avec Git.

Ces deux approches restent différentes du code-first, où la spécification est générée à partir du code applicatif. Dans Apidog, le contrat reste défini avant l’implémentation. Pour une vue plus large sur la gestion d’une spécification comme artefact versionné, consultez le flux de travail API natif Git.

Mode Design-First d’Apidog

Le mode Design-First est l’éditeur visuel d’Apidog. Il convient lorsque vous voulez construire rapidement une API sans écrire manuellement du YAML ou du JSON.

Concrètement, vous pouvez :

1. créer un endpoint ;
2. choisir la méthode HTTP ;
3. définir le chemin ;
4. ajouter les paramètres ;
5. construire les schémas de requête et de réponse ;
6. ajouter des exemples ;
7. générer automatiquement le contrat OpenAPI.

Ce mode réduit les erreurs de syntaxe, car l’interface impose une structure valide. Vous ne risquez pas de casser la spécification avec une accolade manquante ou un type incorrect.

Il est particulièrement utile pour les équipes mixtes où tout le monde ne maîtrise pas OpenAPI :

• développeurs backend ;
• QA ;
• product managers ;
• développeurs juniors ;
• équipes documentation.

Le mode Design-First prend aussi en charge les branches dans Apidog. Plusieurs membres peuvent travailler sur différentes versions du contrat API, puis comparer et réconcilier les changements.

Le principal compromis : si vous pensez déjà directement en OpenAPI, les formulaires peuvent ajouter une couche d’abstraction et ralentir certaines modifications avancées.

Mode Spec-First d’Apidog

Le mode Spec-First, actuellement en bêta, remplace les formulaires par un éditeur de code. Vous écrivez directement votre spécification OpenAPI ou Swagger en YAML ou JSON.

L’éditeur fournit des fonctionnalités proches d’un IDE :

• coloration syntaxique ;
• validation en ligne ;
• auto-complétion adaptée à OpenAPI et Swagger ;
• aperçu automatique des chemins et composants dans la barre latérale ;
• indicateur de synchronisation avec le dépôt Git connecté.

Ce mode est conçu pour les équipes qui veulent gérer leur contrat API comme n’importe quel autre fichier source.

Workflow Git typique

Avec le mode Spec-First, vous pouvez connecter un dépôt GitHub, GitLab ou Azure DevOps via une connexion Git.

Un workflow courant ressemble à ceci :

1. connecter le dépôt Git ;
2. sélectionner le fichier OpenAPI ou Swagger ;
3. modifier la spécification dans Apidog ;
4. valider les changements ;
5. pousser vers le dépôt ;
6. relire les changements dans une pull request.

Le workflow inverse est aussi possible :

1. modifier la spécification dans votre éditeur local ;
2. pousser les changements vers Git ;
3. tirer les changements dans Apidog ;
4. continuer à utiliser les mocks, tests ou docs associés.

La spécification reste donc la source de vérité partagée. Apidog devient une interface de travail sur ce même fichier, et non une copie séparée.

Vous pouvez consulter la configuration complète dans la documentation du Mode Spec-First.

Ce mode est pertinent si votre équipe traite déjà l’infrastructure, la configuration ou les schémas comme du code. Pour approfondir cette approche, consultez l’article sur la spécification API comme code.

Comparaison côte à côte

Les deux modes produisent une spécification OpenAPI exploitable par les outils en aval : documentation, mocks, tests et workflows de validation.

Critère	Mode Design-First	Mode Spec-First bêta
Éditeur	Formulaires visuels et arborescence de schémas	Éditeur YAML/JSON de style IDE
Format	OpenAPI généré automatiquement	OpenAPI ou Swagger écrit à la main
Git	Branches dans Apidog	Synchronisation bidirectionnelle avec GitHub, GitLab et Azure DevOps via connexion Git
Validation	Appliquée par les champs de formulaire	Validation syntaxique en ligne et auto-complétion
Navigation	Liste d’endpoints et dossiers	Aperçu auto-généré des chemins et composants
Courbe d’apprentissage	Faible	Plus élevée
Idéal pour	Équipes mixtes, démarrage rapide, collaboration non experte	Équipes backend, revue en pull request, spec-as-code

Quel mode choisir ?

Choisissez Design-First si…

Utilisez le mode Design-First si votre priorité est d’avancer vite avec une interface guidée.

Il convient particulièrement si :

• tous les contributeurs ne connaissent pas OpenAPI ;
• vous démarrez une nouvelle API ;
• vous voulez éviter les erreurs de syntaxe ;
• les QA ou product managers participent à la conception ;
• vous voulez structurer rapidement endpoints, schémas et exemples.

Exemple de cas d’usage :

Une équipe produit définit un nouveau endpoint /orders/{id} avec les développeurs backend. Le product manager peut relire les paramètres et les exemples sans ouvrir un fichier YAML.

Choisissez Spec-First si…

Utilisez le mode Spec-First si votre API doit être pilotée par un fichier de spécification versionné dans Git.

Il convient particulièrement si :

• votre fichier OpenAPI existe déjà ;
• les changements d’API sont relus en pull request ;
• vous exécutez du linting de spécification en CI ;
• vous voulez une source canonique unique ;
• votre équipe backend préfère travailler en YAML ou JSON ;
• vous traitez la spécification API comme du code.

Exemple de workflow :

git checkout -b update-user-api
# modification du fichier openapi.yaml
git add openapi.yaml
git commit -m "Update user API response schema"
git push origin update-user-api

La pull request peut ensuite être relue comme n’importe quel changement applicatif.

Utilisez les deux si nécessaire

Une approche pratique consiste à :

1. concevoir rapidement les nouveaux endpoints en Design-First ;
2. stabiliser le contrat ;
3. basculer en Spec-First lorsque la revue Git devient prioritaire.

Les deux modes sont deux vues du même contrat. Vous ne choisissez pas un produit différent, seulement une surface d’édition différente.

Comment changer de mode dans Apidog

Pour basculer entre les deux modes :

1. ouvrez votre projet Apidog ;
2. allez dans le module APIs ;
3. regardez en bas à gauche ;
4. utilisez le sélecteur de mode ;
5. choisissez Design-First ou Spec-First.

Le contrat sous-jacent reste partagé. Vos endpoints, schémas et exemples sont conservés.

Avant d’utiliser le mode Spec-First sur un contrat de production, gardez ces points en tête :

• connectez d’abord votre dépôt GitHub, GitLab ou Azure DevOps ;
• vérifiez l’indicateur de synchronisation ;
• testez le comportement de pull, commit et push sur un projet contrôlé ;
• tenez compte du fait que le mode Spec-First est encore en bêta.

FAQ

Le spec-first est-il la même chose que le contract-first ?

En pratique, oui. Les deux termes signifient que la spécification API est définie avant l’implémentation et sert de source de vérité.

Dans Apidog, le mode Spec-First correspond à un workflow contract-first où le contrat est un fichier OpenAPI ou Swagger écrit à la main et synchronisé avec Git.

Le Mode Spec-First fonctionne-t-il avec GitLab et Azure DevOps ?

Oui. Le Mode Spec-First prend en charge la synchronisation Git bidirectionnelle avec GitHub et GitLab. Azure DevOps fonctionne via une connexion Git générique.

Puis-je passer du Design-First au Spec-First sans perdre mon travail ?

Oui. Les deux modes lisent et écrivent le même contrat sous-jacent. Lorsque vous utilisez le bouton de bascule en bas à gauche du module APIs, vous changez d’éditeur, pas de données.

Vos endpoints, schémas, paramètres et exemples restent disponibles.

Conclusion

Si votre équipe veut concevoir rapidement une API avec une interface guidée, commencez avec le mode Design-First.

Si votre équipe veut gérer la spécification comme du code, avec Git, pull requests et fichier OpenAPI canonique, utilisez le mode Spec-First.

Le plus simple : ouvrez le module APIs, basculez entre les deux modes, puis concevez le même endpoint dans chaque interface. Le contrat reste le même ; choisissez le mode qui correspond le mieux à votre workflow réel.