Le mode Spec-First d'Apidog est un espace de travail en version bêta conçu pour les équipes qui considèrent leur spécification OpenAPI comme du code source. Vous écrivez la spécification directement en YAML ou JSON dans un éditeur de style IDE, puis la synchronisez de manière bidirectionnelle avec un dépôt Git connecté. Aucun éditeur basé sur des formulaires ne s'interpose entre vous et le fichier. La spécification *est* le projet. Si vous avez toujours voulu modifier `openapi.yaml` dans un véritable éditeur de code et le pousser sur GitHub sans quitter votre outil API, ce mode est fait pour vous.
Ce guide est la référence complète pour la fonctionnalité elle-même. Il couvre toutes les capacités, le processus de configuration complet, le public visé, les limitations à attendre d'une version bêta et une FAQ pratique. Pour l'idée plus large derrière cette approche, consultez notre workflow API natif Git.
Qu'est-ce que le mode Spec-First d'Apidog ?
Le mode Spec-First est un mode d'édition bêta dans Apidog où la conception de votre API est un document OpenAPI brut. Vous ouvrez le fichier, modifiez le YAML ou le JSON, le validez, le commitez et le poussez vers Git. Apidog maintient la spécification et le dépôt synchronisés dans les deux sens. Tirez la modification d'un coéquipier et votre éditeur se met à jour. Poussez votre modification et le dépôt se met à jour.
Il est conçu spécifiquement pour un type d'équipe : les personnes qui utilisent déjà un workflow Git natif. Les ingénieurs backend, les équipes plateforme et les entreprises 'API-first' qui versionnent leurs contrats via des pull requests s'y sentiront à l'aise. Le fichier de spécification devient la source unique de vérité, et Git gère l'historique, la révision et le branching comme il le fait pour le reste de votre base de code.
Ceci diffère de la façon dont la plupart des outils API fonctionnent. La plupart des outils masquent la spécification derrière un formulaire graphique. Le mode Spec-First vous montre le fichier.
Mode Spec-First vs mode Design-First : un aperçu
Apidog propose deux modes. Le mode Design-First est l'éditeur visuel basé sur des formulaires que la plupart des équipes utilisent au début. Le mode Spec-First est l'approche d'édition de code que ce guide couvre. Voici la version courte. Pour une analyse complète des compromis, lisez notre comparaison spec-first vs design-first.
| Aspect | Mode Design-First | Mode Spec-First (Bêta) |
|---|---|---|
| Éditeur principal | Formulaires visuels et panneaux d'interface utilisateur | Éditeur de code YAML/JSON brut |
| Source de vérité | Base de données de projet Apidog | Le fichier de spécification dans votre dépôt Git |
| Synchronisation Git | Basé sur l'export/import | Synchronisation bidirectionnelle native |
| Idéal pour | Designers visuels, équipes mixtes | Équipes d'ingénieurs natives Git |
| Courbe d'apprentissage | Douce, guidée | Familier si vous connaissez OpenAPI |
Aucun mode n'est « meilleur ». Ils s'adressent à des équipes différentes. Vous pouvez basculer entre eux, ce que nous aborderons ci-dessous.
Fonctionnalités clés
Le mode Spec-First est plus qu'une simple zone de texte. Il regroupe un éditeur, un navigateur, une intégration Git et des contrôles d'équipe. Voici chaque capacité en détail.
L'éditeur OpenAPI de style IDE
Le centre de l'espace de travail est un éditeur de code complet pour votre document OpenAPI. Vous modifiez directement le YAML ou le JSON brut. Il se comporte comme l'éditeur que vous utilisez déjà tous les jours.
Vous bénéficiez de la coloration syntaxique qui colore les clés, les valeurs et la structure afin que le fichier reste lisible à grande échelle. Vous bénéficiez de la validation de schéma qui signale les erreurs par rapport à la spécification OpenAPI au fur et à mesure que vous tapez, de sorte qu'un objet de réponse mal formé ou un champ requis manquant apparaît immédiatement. Vous bénéficiez d'une auto-complétion optimisée pour OpenAPI et Swagger, qui suggère des mots-clés, des noms de champs et une structure valides pendant que vous écrivez.
Cette auto-complétion est la plus utile lorsque vous êtes plongé dans un schéma et que vous ne vous souvenez plus s'il s'agit d'`additionalProperties` ou d'`additionalItems`. L'éditeur connaît la spécification, il vous aide donc à rester correct.
petit aperçu de ce que vous éditeriez :
paths:
/users/{userId}:
get:
summary: Get a user by ID
operationId: getUserById
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: A single user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
Plan navigable analysé automatiquement
Un fichier de spécification brut devient rapidement long. Une véritable API peut comporter des milliers de lignes. Le mode Spec-First résout ce problème avec une barre latérale gauche qui analyse automatiquement le fichier pour en créer un plan visuel.
Au fur et à mesure que vous tapez, Apidog lit le document et construit une structure navigable : chemins, opérations, schémas et composants. Cliquez sur n'importe quel nœud dans le plan et l'éditeur saute à cet endroit dans le fichier. Vous naviguez par signification, pas en faisant défiler. Le plan se met à jour en temps réel à mesure que la spécification change, de sorte qu'il reflète toujours ce qui se trouve réellement dans le fichier.
Cela rend un grand `openapi.yaml` gérable. Vous pensez en termes d'« opération `POST /orders` », et non de « ligne 1 847 ».
Synchronisation Git bidirectionnelle
C'est le cœur du mode. Le mode Spec-First se connecte à votre dépôt Git et synchronise la spécification dans les deux sens.
GitHub et GitLab sont pris en charge directement. Azure DevOps fonctionne via une connexion Git générique, qui vous permet de diriger Apidog vers le dépôt en utilisant des identifiants Git standard. Une fois connecté, tirer les modifications du dépôt les intègre à votre éditeur, et pousser vos modifications les renvoie au dépôt. La spécification reste cohérente pour tous les membres de l'équipe car Git est le pilier partagé.
| Fournisseur | Comment il se connecte |
|---|---|
| GitHub | Intégration directe |
| GitLab | Intégration directe |
| Azure DevOps | Via une connexion Git générique |
Si vous souhaitez une approche ciblée, étape par étape, pour un fournisseur, notre guide de synchronisation de la spécification OpenAPI avec GitHub détaille ce flux exact.
Commit, push et indicateur d'état de synchronisation
Vous ne faites pas que sauvegarder et espérer. Le mode Spec-First suit le modèle Git que vous connaissez déjà. Lorsque vous terminez une modification, vous écrivez un message de commit et commitez le changement. Ensuite, vous le poussez vers le dépôt connecté.
Un indicateur d'état de synchronisation vous tient informé tout au long du processus. Il affiche des états comme « Synchronisé à l'instant » lorsque votre spécification locale correspond au dépôt, et il change lorsque vous avez des modifications non poussées. Vous savez toujours si la version que vous avez devant vous est la version que vos coéquipiers voient. Pas de conjectures, pas de spécifications obsolètes.
Suivi des modifications de fichiers
Avant de commiter, le mode Spec-First vous montre exactement ce qui a changé. Il suit les modifications au niveau du fichier et marque chaque entrée comme modifiée, ajoutée ou supprimée. Vous examinez l'ensemble des modifications comme vous examineriez une sortie de `git status`.
C'est important car cela vous donne un point de contrôle. Vous pouvez confirmer que vous commitez les bonnes modifications et rien de plus. Et si vous décidez qu'une expérience n'a pas fonctionné, vous pouvez annuler les modifications non poussées avant qu'elles n'atteignent le dépôt. Cela maintient votre historique partagé propre. L'exploration locale reste locale jusqu'à ce que vous choisissiez de la pousser.
Projets limités à une branche et un dépôt avec des permissions d'équipe
Un projet Spec-First n'est pas flottant dans l'abstrait. Vous le créez à partir d'un dépôt spécifique et d'une branche spécifique, généralement `main`. Cette portée signifie que le projet pointe toujours vers un endroit réel dans Git. Votre spécification, votre historique et votre branche s'alignent.
Les permissions d'équipe sont configurées lors de la configuration. Vous décidez qui peut accéder au projet et ce qu'ils peuvent faire, de sorte que les personnes travaillant sur le contrat sont celles que vous avez désignées. Étant donné que le projet est lié à un dépôt et à une branche, votre modèle d'accès peut refléter le modèle d'accès que vous appliquez déjà dans Git.
Comment configurer le mode Spec-First
La configuration est un processus court et linéaire. Suivez ces étapes. Le guide officiel est disponible sur docs.apidog.com/spec-first-mode-beta-2058268m0 si vous souhaitez des captures d'écran en accompagnement.
- Changez de mode. Ouvrez le module API dans Apidog. Trouvez le bouton de bascule de mode en bas à gauche du module et passez du mode Design-First au mode Spec-First.
- Connectez votre fournisseur Git. Autorisez GitHub ou GitLab directement. Pour Azure DevOps, configurez une connexion Git générique avec vos identifiants Git.
- Créez un projet à partir de votre dépôt. Choisissez le dépôt qui contient votre spécification et sélectionnez la branche, généralement `main`. Apidog limite le nouveau projet à ce dépôt et cette branche.
- Configurez les permissions d'équipe. Lors de la configuration, définissez qui peut accéder au projet et ce qu'ils peuvent modifier.
- Modifiez la spécification. Ouvrez votre `openapi.yaml` ou `openapi.json` dans l'éditeur de style IDE. Utilisez le plan sur la gauche pour naviguer. Appuyez-vous sur la validation et l'auto-complétion pendant que vous écrivez.
- Commitez vos modifications. Rédigez un message de commit clair. Examinez d'abord les modifications suivies. Annulez tout ce que vous ne voulez pas conserver.
- Poussez vers le dépôt. Poussez votre commit vers la branche connectée.
- Vérifiez la synchronisation. Vérifiez l'indicateur d'état de synchronisation. Lorsqu'il affiche « Synchronisé à l'instant », votre spécification et votre dépôt correspondent.
C'est la boucle complète : changer, connecter, créer, éditer, commiter, pousser, vérifier.
Un workflow quotidien typique
Voici comment le mode se ressent en pratique une fois configuré.
Vous commencez votre journée en tirant la dernière version de la branche connectée, de sorte que votre éditeur reflète ce que vos coéquipiers ont fusionné pendant la nuit. Vous ouvrez le plan, cliquez sur l'opération sur laquelle vous travaillez et commencez à modifier le YAML. Un nouveau point de terminaison nécessite un corps de requête, vous définissez donc un schéma. L'auto-complétion vous aide à obtenir les bons noms de champs, et la validation détecte une faute de frappe dans un `$ref` avant qu'elle ne devienne un problème.
Lorsque le point de terminaison semble bon, vous vérifiez le suivi des modifications de fichiers. Il affiche vos modifications. Vous rédigez un message de commit comme `Ajout du point de terminaison POST /invoices`, commitez et poussez. L'indicateur d'état passe à « Synchronisé à l'instant ». Un coéquipier examine le changement dans une pull request normale, car la spécification vit dans Git comme tout le reste.
Voici le type d'ajout que vous feriez dans ce flux :
components:
schemas:
Invoice:
type: object
required: [id, amount, currency]
properties:
id:
type: string
format: uuid
amount:
type: integer
description: Amount in the smallest currency unit
currency:
type: string
example: USD
status:
type: string
enum: [draft, sent, paid]
L'ensemble du cycle reste au sein des outils auxquels vous faites confiance. La spécification est du code, et vous la traitez comme du code.
Qui devrait utiliser le mode Spec-First
Le mode Spec-First convient mieux à certaines équipes qu'à d'autres. Soyez honnête sur l'équipe à laquelle vous appartenez.
Utilisez le mode Spec-First si votre équipe vit déjà dans Git. Si vous examinez les contrats API dans les pull requests, si vous voulez que la spécification soit versionnée à côté de votre code de service, ou si vos ingénieurs préfèrent éditer le YAML directement, ce mode supprime les frictions. Il convient parfaitement aux équipes backend et plateforme qui considèrent le document OpenAPI comme un artefact de première classe.
Choisissez plutôt le mode Design-First si vous souhaitez une expérience guidée et visuelle. Les équipes où des non-ingénieurs contribuent à la conception, ou toute personne préférant cliquer sur des formulaires plutôt que d'écrire du YAML, progresseront plus rapidement avec ce mode. Les équipes mixtes où le produit et la conception interviennent sur les points de terminaison préfèrent souvent l'éditeur visuel. Il n'y a pas de mauvaise réponse. Choisissez le mode qui correspond à la façon dont votre équipe travaille réellement. Notre article comparatif approfondit cette décision.
Limitations et remarques sur la version bêta
Le mode Spec-First est une version bêta. Ce mot a une réelle signification, alors ajustez vos attentes en conséquence.
En tant que version bêta, la fonctionnalité est encore en maturation. Les capacités et le comportement peuvent changer à mesure qu'Apidog affine le mode en fonction des retours. L'intégration directe des fournisseurs couvre GitHub et GitLab aujourd'hui, tandis qu'Azure DevOps s'appuie sur la connexion Git générique plutôt que sur une intégration dédiée. Si votre équipe dépend d'un fournisseur Git ou d'un workflow spécifique, confirmez qu'il correspond à vos besoins avant de confier un projet critique à ce mode.
Étant donné que la spécification se synchronise avec un dépôt en direct, la discipline Git normale s'applique. Commitez délibérément, poussez intentionnellement et utilisez l'option d'annulation lorsqu'une modification ne doit pas être déployée. Le suivi des modifications de fichiers et l'indicateur de synchronisation sont là pour vous protéger, mais la responsabilité d'un historique propre vous incombe toujours. Traitez la version bêta comme vous traiteriez tout nouvel outil touchant votre branche principale : essayez-la d'abord sur un dépôt non critique, puis étendez-la une fois que vous faites confiance au flux.
L'avantage d'une version bêta est l'influence. Les premiers retours façonnent l'orientation de la fonctionnalité, donc si quelque chose manque à votre workflow, cela vaut la peine d'être signalé.
FAQ
Le mode Spec-First est-il gratuit ?
Le mode Spec-First est une fonctionnalité bêta au sein d'Apidog. L'accès dépend de votre plan Apidog, vérifiez donc la disponibilité du mode par rapport à votre plan actuel et au statut bêta. Étant donné qu'il est en version bêta, le moyen le plus simple est de l'activer dans le module API et de voir s'il est disponible pour votre compte.
Quels fournisseurs Git sont pris en charge ?
GitHub et GitLab sont pris en charge via une intégration directe. Azure DevOps fonctionne via une connexion Git générique, qui utilise des identifiants Git standard pour diriger Apidog vers votre dépôt. D'autres hôtes Git peuvent également fonctionner via cette connexion générique, car elle s'appuie sur Git standard plutôt que sur une API spécifique au fournisseur.
Puis-je revenir au mode Design-First ?
Oui. Le bouton de bascule de mode se trouve en bas à gauche du module API, et vous pouvez y basculer entre le mode Spec-First et le mode Design-First. Vous n'êtes pas enfermé. Choisissez le mode qui convient au projet que vous avez devant vous.
Quels formats de fichier puis-je modifier ?
Vous modifiez votre document OpenAPI en YAML ou JSON brut dans l'éditeur de style IDE. L'éditeur fournit la coloration syntaxique, la validation de schéma et l'auto-complétion pour OpenAPI et Swagger, afin que vous restiez correct en écrivant dans l'un ou l'autre format.
Qu'advient-il de mes modifications non poussées ?
Les modifications non poussées restent locales jusqu'à ce que vous les poussiez. Le mode Spec-First suit chaque modification comme modifiée, ajoutée ou supprimée, et l'indicateur de synchronisation montre quand vous avez du travail qui n'a pas atteint le dépôt. Si vous décidez de ne pas conserver une modification, annulez-la avant de la pousser et elle n'entrera jamais dans votre historique partagé.
Conclusion
Le mode Spec-First d'Apidog réunit l'éditeur OpenAPI et Git en un seul endroit. Vous modifiez la spécification en YAML ou JSON, la naviguez via un plan analysé automatiquement, la validez au fur et à mesure que vous tapez, et la synchronisez de manière bidirectionnelle avec GitHub, GitLab ou Azure DevOps. Les messages de commit, le push, le suivi des modifications et un indicateur de synchronisation clair vous offrent le workflow Git que vous connaissez déjà, appliqué à votre contrat API.
C'est une version bêta, et elle s'adresse aux équipes natives Git qui souhaitent que la spécification soit du code source. Si c'est votre cas, ce mode mérite un examen sérieux. Activez-le dans le module API, connectez un dépôt et essayez un petit cycle d'édition-commit-push pour vous familiariser avec le flux. Lorsque vous êtes prêt, essayez le mode Spec-First dans la documentation et connectez-le à un dépôt en lequel vous avez confiance.