Il y a deux écoles dans chaque équipe API avec laquelle j'ai travaillé.
L'une écrit sa spécification OpenAPI à la main, la commite dans un répertoire specs/ et considère Git comme la source de vérité. L'autre clique à travers un concepteur visuel, exporte la spécification lorsque la CI se plaint, et corrige toute dérive que les deux représentations ont accumulée depuis mardi dernier.
J'ai vécu dans les deux camps. Le premier est plus lent le premier jour et plus rapide le quatre-vingt-dixième jour. Le second est l'inverse. Et jusqu'à il y a environ un mois, l'outil de conception API que j'utilise le plus — Apidog — ne s'adressait vraiment qu'au second camp. Son concepteur visuel est excellent. Son aller-retour YAML était une fonctionnalité que vous deviez défendre lors des revues de code.
Puis, mi-avril, le Mode Spec-First (Bêta) est apparu dans la boîte de dialogue Nouveau Projet. Je n'ai délibérément pas écrit à ce sujet le jour du lancement. Je voulais d'abord l'utiliser sur quelque chose de réel, et je voulais attendre suffisamment longtemps pour que les bugs de début de semaine aient une chance de faire surface. Un mois est à peu près le bon laps de temps. Cet article est ce que j'ai trouvé après avoir passé une matinée avec la bêta sur une spécification OpenAPI d'un de mes projets personnels — ce que je dirais à un coéquipier avant qu'il ne l'essaie, et où il convient ou non.
Ce que le Mode Spec-First change réellement
En bref : Apidog propose désormais deux modes de projet, et ce sont des produits intrinsèquement différents en dessous.
Le mode par défaut est celui que la plupart des gens connaissent. Vous cliquez sur + Nouveau Projet, vous obtenez une arborescence de dossiers et de formulaires visuels, et vous construisez des points de terminaison en remplissant des champs. La spécification OpenAPI est générée en arrière-plan. Cela fonctionne, surtout pour les équipes qui n'ont pas déjà une forte habitude du YAML.
Le Mode Spec-First remplace l'éditeur de formulaires par un véritable éditeur de code pour les fichiers bruts .yaml et .json, plus une synchronisation bidirectionnelle avec votre dépôt Git. Votre spécification OpenAPI est le fichier sur le disque, pas une sérialisation de clics. Il y a la coloration syntaxique, l'autocomplétion par rapport au schéma OpenAPI, et un panneau « Analyse de Répertoire en Temps Réel » qui construit un aperçu des points de terminaison dans la barre latérale à partir de votre code au fur et à mesure que vous tapez.
Ce dernier détail est celui que je mettrais en avant si je devais faire une démonstration à un sceptique. La raison de l'existence des concepteurs visuels n'est pas que le YAML est difficile — c'est que le YAML cache la structure jusqu'à ce que vous l'ayez déjà dépassée. La vue en arborescence d'Apidog résout ce problème sans vous obliger à abandonner le fichier. Vous écrivez la spécification, vous obtenez la navigation. Les deux coexistent à l'écran.
La thèse, s'il y en a une : le développement axé sur la spécification n'a jamais consisté à préférer les éditeurs de texte. Il s'agissait de savoir qui possède l'artefact. Le Mode Spec-First fait de l'artefact le fichier dans votre dépôt, point final. L'interface utilisateur est une fenêtre sur celui-ci, pas un enveloppement autour de lui.
La configuration, de bout en bout
Voici le chemin que j'ai suivi. Cela a pris moins de dix minutes, dont la majeure partie était l'autorisation Git.
1. Créez le projet dans le bon mode. Depuis l'écran des projets, + Nouveau Projet → Général → Mode Spec-first. Le sélecteur de mode est facile à manquer si vous avez créé des projets en pilote automatique pendant un an — le Mode Général est signalé comme « Recommandé » et votre œil glisse juste après la deuxième tuile. Ralentissez ici.
2. Connectez-vous à votre dépôt Git. Faites défiler jusqu'à Se connecter avec le dépôt Git et autorisez votre fournisseur. J'ai utilisé GitHub ; la documentation couvre les autres. Ensuite, choisissez l'Organisation, le Dépôt et la Branche principale. Apidog synchronisera les fichiers de spécification de cette branche comme votre copie de travail.
3. Configurez le projet. Saisissez un Nom de projet, définissez les permissions d'équipe, et Créer. La première synchronisation tire tous les fichiers .yaml et .json qui résident dans le dépôt vers l'espace de travail d'Apidog.
4. Modifiez la spécification comme un fichier, pas un formulaire. Ouvrez l'un des fichiers YAML. Vous obtenez un véritable éditeur, une autocomplétion consciente du schéma, et l'aperçu des points de terminaison se matérialisant dans la barre latérale au fur et à mesure que vous tapez. Si vous avez passé du temps dans VS Code avec l'extension OpenAPI, cela vous semblera familier — sauf que l'aperçu est lié à la navigation, et cliquer sur un point de terminaison vous fait sauter à la bonne ligne.
5. Commitez et poussez. En haut à droite, Commit & Push. La boîte de dialogue s'ouvre sur une section Modifications listant les fichiers modifiés, un champ Message de commit, et deux boutons : Pousser ou Annuler toutes les modifications. Il n'y a pas d'étape de staging séparée — tout ce qui se trouve dans Modifications ira au commit. C'est une simplification délibérée, et pour la plupart des workflows d'édition de spécification, c'est le bon choix.
6. Surveillez l'indicteur de synchronisation. Coin inférieur gauche — vous pouvez le voir comme Synchronisé à l'instant dans la Figure 1. Il vous indique si vos modifications locales sont poussées, tirées ou désynchronisées avec le dépôt distant. J'ai laissé cela ouvert dans un coin de mon écran et c'est devenu la chose à laquelle je faisais plus confiance que les boîtes de dialogue modales. Si l'indicateur est vert, vous et le dépôt êtes d'accord.
C'est toute la surface d'interaction. Six étapes, pas de moteur de synchronisation séparé à configurer, pas de plugins à installer.
Ce que j'ai remarqué et que la documentation ne dit pas
Trois choses à signaler, toutes issues d'une matinée passée à explorer.
La vue d'ensemble se met à jour plus vite que je ne l'imaginais. J'ai utilisé plusieurs « éditeurs OpenAPI en direct » par le passé et la plupart d'entre eux re-parsers au moment de la sauvegarde, ce qui signifie un délai de 30 secondes entre l'ajout d'un point de terminaison et son apparition dans la barre latérale. L'aperçu d'Apidog s'est mis à jour au fur et à mesure que je tapais — suffisamment proche de l'instantané pour que j'arrête de vérifier. Cela semble être une petite chose. Ce n'est pas le cas. C'est la différence entre faire confiance à l'aperçu comme aide à la navigation et le consulter comme un rapport d'état.
L'intégration Git est véritablement bidirectionnelle. J'ai édité le même fichier dans mon clone local et poussé depuis le terminal pendant qu'Apidog était ouvert. Apidog l'a remarqué, l'indicateur de synchronisation est passé à « en retard », et un clic a tiré les modifications dans l'éditeur sans boîte de dialogue de fusion. La synchronisation bidirectionnelle promise par la documentation est l'expérience réelle, pas un résumé marketing. Si vous avez un coéquipier qui refuse d'utiliser autre chose que Vim, il peut continuer à utiliser Vim, et vous pouvez continuer à utiliser Apidog, et le fichier dans le dépôt reste la seule chose que vous éditez tous les deux.
Il n'y a pas de retour possible vers le concepteur visuel dans le même projet. C'est intentionnel, mais il est bon de le savoir avant de s'engager. Si vous choisissez le Mode Spec-First à la création, ce projet est axé sur la spécification. Vous ne pouvez pas changer de projet en cours de route car les modèles de données sous-jacents sont différents. Pour une équipe qui souhaite les deux modes sur la même spécification, le flux de travail est le suivant : conserver la spécification dans un dépôt, pointer un projet Spec-First vers celle-ci, et laisser les utilisateurs du mode visuel ouvrir un projet séparé qui importe de la même source. Pas sans accroc, mais fonctionnel.
Où il convient, et où il ne convient pas
Je vais l'utiliser en production. C'est la réponse la plus directe que je puisse donner. La combinaison d'un véritable éditeur, d'une autocomplétion qui respecte le schéma OpenAPI, et d'un indicateur de synchronisation auquel je peux faire confiance est ce que j'attendais d'Apidog depuis deux ans.
Mais voici la version honnête de à qui cela s'adresse.
Il convient si vous écrivez déjà l'OpenAPI à la main, ou si vous souhaitez le faire. Il convient si votre CI exécute spectral lint ou génère des SDK clients à partir de la spécification et que la spécification doit de toute façon se trouver dans Git. Il convient si vous avez un ingénieur dans l'équipe qui, autrement, ouvrirait des pull requests contre le fichier YAML depuis VS Code, et que vous voulez que tout le monde converge sur un seul outil sans les forcer à quitter leur clavier. Et il convient particulièrement bien si vous avez géré la dérive entre « la spécification dans Apidog » et « la spécification dans le dépôt » avec une étape make export que personne ne faisait confiance.
Il ne convient pas si votre équipe n'a jamais touché à OpenAPI et que le concepteur visuel est la raison pour laquelle ils peuvent contribuer. Pour ces équipes, le mode par défaut reste le bon choix. Le Mode Spec-First échange la facilité d'intégration contre la fidélité, et cet échange est erroné lorsque la plupart de vos contributeurs ne sont pas des spécialistes des API.
Il ne convient pas non plus, pour l'instant, aux équipes qui ont besoin de mélanger les deux modes sur le même projet. La bêta est vraiment une bêta sur ce point. Je m'attendrais à ce que cela s'assouplisse au cours des prochaines versions.
Le point à retenir
Le développement axé sur la spécification signifiait auparavant se passer des outils de conception d'API. Soit vous viviez en YAML et abandonniez les runners de tests et les serveurs mock, soit vous viviez dans un concepteur visuel et abandonniez Git comme source de vérité. Le mouvement intéressant du Mode Spec-First est qu'Apidog a cessé de vous demander de choisir.
Le fichier dans votre dépôt est le fichier dans l'éditeur. L'aperçu est une vue, pas un état. La synchronisation Git est le fil conducteur, pas une fonctionnalité. Si vous attendiez une plateforme API pour prendre au sérieux l'approche « spec-first » au lieu de la traiter comme une option d'exportation, c'est celle que j'essaierais.
La bêta est disponible dès aujourd'hui dans la boîte de dialogue Nouveau Projet. Téléchargez Apidog, choisissez le Mode Spec-First à la création, et pointez-le vers un dépôt auquel vous faites déjà confiance. Le premier commit prend dix minutes. La décision de le conserver prend environ une semaine.