Le module APIs d'Apidog vous offre deux façons de construire la même chose : un contrat API. L'une utilise des formulaires visuels. L'autre utilise un éditeur de code brut intégré à Git. Les deux produisent un OpenAPI valide. La différence réside dans la façon dont votre équipe travaille au quotidien, et le choix qui convient dépend moins de l'outil et davantage de vos habitudes.
Ce guide explore la décision design-first vs spec-first dans Apidog : ce qu'est chaque mode, comment ils gèrent Git, et quelles équipes ont tendance à choisir quel mode. Vous passez de l'un à l'autre via un simple bouton bascule en bas à gauche du module APIs, le choix n'est donc pas permanent. Mais choisir le bon mode par défaut réduit les frictions.
Les deux philosophies
Avant les modes, l'état d'esprit. Les deux approches partagent une règle : vous définissez le contrat API avant d'écrire l'implémentation. Le contrat est la source de vérité. Le code, les tests, les mocks et la documentation en découlent tous.
Design-first signifie que vous façonnez ce contrat via une interface structurée. Vous ajoutez des points de terminaison, des paramètres et des schémas via des formulaires et des listes déroulantes. L'outil garantit que la sortie est valide car vous ne pouvez saisir que des valeurs valides.
Spec-first (souvent appelé contract-first) signifie que vous écrivez le contrat directement sous forme de fichier de spécification : OpenAPI en YAML ou JSON. La spécification *est* votre surface de travail. Vous la modifiez comme du code source.
Ces termes se chevauchent en pratique. « Contract-first » et « spec-first » sont des quasi-synonymes, et de nombreuses équipes utilisent « design-first » de manière lâche pour désigner toute approche où le contrat précède le code. La distinction utile ici est concrète : dans Apidog, un mode vous offre des formulaires, l'autre un éditeur de texte. C'est la ligne qui compte lorsque vous choisissez.
Il est important de les distinguer du développement d'API design-first vs code-first. Code-first génère la spécification *à partir* des annotations de votre implémentation, le code prime donc. Les deux modes Apidog maintiennent le contrat avant le code. Ils ne sont simplement pas d'accord sur la façon de l'élaborer. Pour une vue d'ensemble plus large du traitement de votre spécification comme un artefact versionné, consultez notre aperçu du flux de travail API natif Git.
Mode Design-First d'Apidog
Le Mode Design-First est le concepteur visuel. Vous construisez des points de terminaison via une interface guidée : choisissez une méthode, nommez le chemin, ajoutez des paramètres de requête et de chemin, définissez les schémas de requête et de réponse via un éditeur arborescent, et joignez des exemples. Apidog génère l'OpenAPI sous-jacent pour vous en arrière-plan.
Ce mode est le mode par défaut pour la plupart des équipes, et pour une bonne raison. Vous n'avez pas besoin de mémoriser la syntaxe OpenAPI. L'éditeur de schéma applique une structure, vous ne pouvez donc pas livrer une spécification avec une accolade mal placée ou un type invalide. Les composants réutilisables, comme un schéma d'erreur partagé ou un en-tête commun, sont à portée de quelques clics.
Le Mode Design-First prend également en charge les branches, de sorte que les équipes peuvent travailler sur différentes versions de la conception d'API en parallèle et les réconcilier ultérieurement. Les réviseurs voient un diff structuré plutôt qu'un texte brut, ce qui facilite la lecture des modifications de contrat pour les personnes qui ne sont pas habituées au YAML.
Le compromis : vous travaillez à travers une abstraction. Si vous pensez déjà en OpenAPI, les formulaires peuvent sembler des clics supplémentaires entre vous et la spécification que vous avez en tête.
Mode Spec-First d'Apidog
Le Mode Spec-First, actuellement en version bêta, inverse cela. Au lieu de formulaires, vous obtenez un éditeur de code de style IDE et vous écrivez la spécification OpenAPI ou Swagger directement en YAML ou JSON. Il est conçu pour les équipes qui veulent que leur définition d'API réside dans Git comme n'importe quel autre fichier source.
L'éditeur se comporte comme celui de votre éditeur de code : coloration syntaxique, validation en ligne et auto-complétion optimisée pour les schémas OpenAPI et Swagger. Au fur et à mesure que vous tapez, une barre latérale gauche analyse automatiquement votre spécification en un aperçu des chemins et des composants, afin que vous puissiez naviguer dans un grand fichier sans faire défiler. Un indicateur de synchronisation montre si vos modifications locales sont en phase avec le référentiel connecté.
Le point clé est la synchronisation Git bidirectionnelle. Vous connectez un référentiel sur GitHub ou GitLab (Azure DevOps fonctionne via une connexion Git générique), et Apidog synchronise votre fichier de spécification dans les deux sens. Modifiez dans Apidog, puis validez et poussez directement depuis l'application. Ou modifiez la spécification dans votre éditeur de code, poussez à partir de là, et tirez les changements vers Apidog. Le fichier de spécification est la vérité partagée, et les deux interfaces restent alignées. Vous pouvez lire la configuration complète dans la documentation du Mode Spec-First.
Ce mode traite votre contrat API comme vous traiteriez tout autre artefact de code : examiné dans les pull requests, versionné aux côtés des services qui l'implémentent, et comparé ligne par ligne. Si c'est ainsi que votre équipe gère déjà l'infrastructure et la configuration, consultez notre analyse plus approfondie de la spécification API comme code pour en comprendre la raison.
Comparaison côte à côte
Les deux modes produisent le même OpenAPI et prennent en charge le mocking, les tests et la documentation en aval. Ils diffèrent dans la manière dont vous rédigez et versionnez la spécification.
| Mode Design-First | Mode Spec-First (bêta) | |
|---|---|---|
| Éditeur | Formulaires visuels et arborescence de schémas | Éditeur de code YAML/JSON de style IDE |
| Format de spécification | OpenAPI (généré pour vous) | OpenAPI / Swagger, écrit à la main |
| Flux de travail Git | Support des branches au sein d'Apidog | Synchronisation bidirectionnelle avec GitHub, GitLab, Azure DevOps (Connexion Git) ; commit et push depuis l'application |
| Validation | Appliquée par les champs de formulaire | Validation syntaxique en ligne et auto-complétion |
| Navigation | Liste des points de terminaison et dossiers | Aperçu auto-analysé dans la barre latérale gauche |
| Courbe d'apprentissage | Faible ; aucune connaissance OpenAPI requise | Plus élevée ; suppose une maîtrise d'OpenAPI |
| Idéal pour | Équipes aux compétences variées, intégration rapide | Ingénieurs qui traitent la spécification comme du code |
Quelle équipe devrait choisir quel mode
Utilisez le Mode Design-First si vos contributeurs ne sont pas tous des experts OpenAPI. Les chefs de produit, l'assurance qualité et les ingénieurs juniors peuvent tous ajouter ou réviser des points de terminaison sans apprendre la syntaxe des spécifications. C'est aussi la voie la plus rapide lorsque vous démarrez une nouvelle API à partir de zéro et que vous souhaitez avancer rapidement sur la structure sans vous soucier du formatage.
Utilisez le Mode Spec-First si votre spécification existe déjà, ou devrait exister, dans un dépôt Git à côté de votre code de service. Les équipes backend qui examinent les modifications d'API dans les pull requests, exécutent le linting des spécifications en CI, ou veulent un fichier YAML canonique unique à travers les outils se sentiront à l'aise. La synchronisation bidirectionnelle signifie qu'Apidog cesse d'être une copie séparée de la vérité et devient une fenêtre sur le même fichier que votre dépôt contient.
Une voie médiane pratique : de nombreuses équipes conçoivent de nouveaux points de terminaison en Mode Design-First pour la rapidité, puis passent au Mode Spec-First une fois que l'API mûrit et que la révision Git devient la priorité. Les modes ne sont pas des produits rivaux. Ce sont deux vues d'un même contrat.
Comment changer de mode
Le changement se fait via un simple bouton bascule. Ouvrez le module APIs dans votre projet Apidog et regardez dans le coin inférieur gauche, où se trouve le sélecteur de mode. Basculez-le, et le même contrat s'affichera dans l'autre mode.
Quelques points à garder à l'esprit lorsque vous changez :
- La spécification sous-jacente est partagée, de sorte que vos points de terminaison, schémas et exemples sont conservés. Vous changez la surface d'édition, pas la reconstruction de l'API.
- Pour utiliser la synchronisation Git du Mode Spec-First, connectez d'abord votre référentiel GitHub, GitLab ou Azure DevOps. Une fois connecté, l'indicateur de synchronisation vous indique si vos modifications sont validées et poussées.
- Étant donné que le Mode Spec-First est en version bêta, essayez-le sur un projet où vous pouvez confirmer le comportement de synchronisation avant de vous y fier pour un contrat de production.
Vous pouvez alterner selon l'évolution de vos besoins, traitez donc ce choix comme un mode par défaut plutôt qu'un engagement.
FAQ
Le "spec-first" est-il la même chose que le "contract-first" ?
En pratique, oui. « Spec-first » et « contract-first » signifient tous deux que vous rédigez la spécification API avant l'implémentation, et les deux traitent cette spécification comme la source de vérité. Le Mode Spec-First d'Apidog est un flux de travail 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 directement. Azure DevOps fonctionne via une connexion Git générique, vous pouvez donc également synchroniser votre fichier de spécification vers un référentiel hébergé sur Azure.
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, de sorte que vos points de terminaison, schémas et exemples restent intacts lorsque vous actionnez le bouton bascule en bas à gauche du module APIs. Vous échangez l'éditeur, pas les données.
Vous ne savez pas quel mode convient à votre équipe ? Ouvrez le module APIs, essayez le bouton de bascule de mode en bas à gauche, et concevez votre prochain point de terminaison des deux manières. Le contrat est le même dans les deux cas ; choisissez l'interface qui correspond à la façon dont votre équipe travaille déjà.