Antoine Laurent

Posted on Jun 3 • Originally published at apidog.com

Mode Spec-First Apidog : Qu'est-ce que c'est ?

Le mode Spec-First d’Apidog est un espace de travail bêta pour les équipes qui traitent leur spécification OpenAPI comme du code source. Vous éditez directement openapi.yaml ou openapi.json dans un éditeur de style IDE, puis vous synchronisez le fichier dans les deux sens avec un dépôt Git connecté. Pas d’éditeur par formulaires entre vous et la spec : la spécification devient le projet.

Essayez Apidog aujourd’hui

Ce guide explique comment utiliser ce mode concrètement : configuration Git, édition OpenAPI, commit, push, suivi des changements, limites de la bêta et cas d’usage recommandés. Pour comprendre l’approche globale, consultez aussi le 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ù votre contrat API est un document OpenAPI brut.

Le workflow est simple :

Ouvrir la spécification en YAML ou JSON.
Modifier le fichier directement.
Valider la structure OpenAPI pendant l’édition.
Commiter les changements.
Pousser vers le dépôt Git connecté.
Tirer les modifications des autres membres de l’équipe quand elles arrivent.

Ce mode cible les équipes qui utilisent déjà Git comme source de vérité : backend, plateforme, API-first, ou toute équipe qui révise ses contrats API via pull requests.

La différence principale avec un outil API classique : Apidog ne masque pas la spécification derrière des formulaires. Vous travaillez sur le fichier.

Mode Spec-First vs mode Design-First

Apidog propose deux approches :

Design-First : édition visuelle via formulaires.
Spec-First : édition directe du fichier OpenAPI.

Pour une comparaison plus détaillée, consultez la comparaison spec-first vs design-first.

Aspect	Mode Design-First	Mode Spec-First bêta
Éditeur principal	Formulaires visuels et panneaux UI	Éditeur YAML/JSON brut
Source de vérité	Base de données du projet Apidog	Fichier de spécification dans Git
Synchronisation Git	Export/import	Synchronisation bidirectionnelle native
Idéal pour	Équipes mixtes, design visuel	Équipes d’ingénieurs natives Git
Courbe d’apprentissage	Guidée	Naturelle si vous connaissez OpenAPI

Aucun mode n’est meilleur dans l’absolu. Choisissez selon votre workflow réel : formulaires pour la collaboration visuelle, fichier brut pour les équipes qui versionnent tout dans Git.

Fonctionnalités clés

1. Éditer OpenAPI dans un éditeur de style IDE

Le cœur du mode Spec-First est un éditeur de code pour YAML et JSON.

Vous pouvez y modifier directement votre document OpenAPI avec :

coloration syntaxique ;
validation de schéma OpenAPI ;
auto-complétion pour OpenAPI et Swagger ;
détection rapide des champs manquants ou mal formés ;
navigation dans les chemins, opérations, schémas et composants.

Exemple d’opération OpenAPI que vous pouvez éditer directement :

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'

L’auto-complétion devient utile dès que la spec grossit : noms de champs, structure attendue, $ref, composants, schémas imbriqués, etc.

2. Naviguer dans une grande spécification

Un fichier openapi.yaml peut rapidement atteindre plusieurs milliers de lignes. Le mode Spec-First analyse automatiquement le document et génère un plan dans la barre latérale.

Vous pouvez naviguer par concepts :

GET /users/{userId} ;
POST /orders ;
components.schemas.User ;
components.responses.NotFound.

Au lieu de chercher une ligne précise, vous cliquez sur une opération ou un schéma, et l’éditeur saute directement à l’emplacement correspondant.

3. Synchroniser la spec avec Git dans les deux sens

Le mode Spec-First connecte votre projet Apidog à un dépôt Git. La synchronisation fonctionne dans les deux sens :

pull : récupérer les changements du dépôt vers Apidog ;
commit : enregistrer vos modifications ;
push : envoyer vos changements vers Git.

Fournisseurs pris en charge :

Fournisseur	Connexion
GitHub	Intégration directe
GitLab	Intégration directe
Azure DevOps	Connexion Git générique

Pour un guide dédié à GitHub, consultez le guide de synchronisation de la spécification OpenAPI avec GitHub.

4. Commiter, pousser et vérifier l’état de synchronisation

Le mode Spec-First suit un workflow Git classique :

Modifier la spec.
Vérifier les fichiers modifiés.
Écrire un message de commit.
Commiter.
Pousser vers la branche connectée.
Vérifier l’indicateur de synchronisation.

L’indicateur affiche l’état de la spec, par exemple lorsque votre version locale est synchronisée avec le dépôt. Vous savez donc si vos changements ont bien été poussés ou s’ils restent locaux.

5. Suivre les modifications avant commit

Avant de commiter, Apidog affiche les changements détectés au niveau des fichiers :

modifié ;
ajouté ;
supprimé.

Utilisez ce point de contrôle comme un git status visuel. Avant de pousser :

vérifiez que seules les modifications voulues sont présentes ;
annulez les changements expérimentaux ;
évitez de polluer l’historique partagé.

6. Travailler sur un dépôt et une branche précis

Un projet Spec-First est créé depuis :

un dépôt Git spécifique ;
une branche spécifique, souvent main.

Cette contrainte garde le projet aligné avec un emplacement réel dans Git. Vous pouvez aussi configurer les permissions d’équipe pendant la création du projet pour contrôler qui peut accéder à la spec et la modifier.

Comment configurer le mode Spec-First

La documentation officielle est disponible ici : docs.apidog.com/spec-first-mode-beta-2058268m0.

Voici le flux de configuration pratique.

Étape 1 — Passer en mode Spec-First

Dans Apidog :

Ouvrez le module API.
Repérez le bouton de changement de mode en bas à gauche.
Passez de Design-First à Spec-First.

Étape 2 — Connecter Git

Connectez votre fournisseur :

GitHub via l’intégration directe ;
GitLab via l’intégration directe ;
Azure DevOps via une connexion Git générique.

Pour Azure DevOps ou un autre hôte Git, préparez vos identifiants Git standard.

Étape 3 — Créer un projet depuis le dépôt

Sélectionnez :

le dépôt contenant openapi.yaml ou openapi.json ;
la branche à utiliser, par exemple main.

Le projet Apidog sera lié à ce dépôt et à cette branche.

Étape 4 — Configurer les permissions

Définissez les membres qui peuvent accéder au projet et leurs droits. L’objectif est de faire correspondre l’accès Apidog au modèle de collaboration que vous utilisez déjà dans Git.

Étape 5 — Modifier la spécification

Ouvrez le fichier OpenAPI dans l’éditeur et travaillez directement sur le YAML ou le JSON.

Exemple d’ajout de schéma :

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]

Pendant l’édition, utilisez :

le plan de navigation ;
l’auto-complétion ;
la validation OpenAPI ;
le suivi des changements.

Étape 6 — Commiter

Avant le commit :

ouvrez la liste des modifications ;
vérifiez les fichiers modifiés ;
annulez ce qui ne doit pas être conservé ;
écrivez un message de commit clair.

Exemple :

Ajout du schéma Invoice

ou :

Ajout du endpoint POST /invoices

Étape 7 — Pousser vers Git

Poussez le commit vers la branche connectée. Vos coéquipiers peuvent ensuite récupérer la modification ou la relire via le workflow Git habituel.

Étape 8 — Vérifier la synchronisation

Après le push, vérifiez l’indicateur d’état. Lorsque la synchronisation est à jour, la spec locale et le dépôt correspondent.

Exemple de workflow quotidien

Un workflow typique ressemble à ceci :

Vous commencez par tirer la dernière version de la branche connectée.
Vous ouvrez le plan de la spécification.
Vous cliquez sur l’opération à modifier, par exemple POST /invoices.
Vous ajoutez un requestBody ou un nouveau schéma.
La validation détecte une erreur éventuelle dans un $ref.
Vous corrigez la spec.
Vous vérifiez les changements.
Vous commitez.
Vous poussez vers Git.
Votre équipe relit la modification via le processus habituel.

Exemple d’ajout d’un endpoint :

paths:
  /invoices:
    post:
      summary: Create an invoice
      operationId: createInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'

Le point important : la spécification reste du code. Elle est éditée, versionnée et revue comme le reste de votre base de code.

Qui devrait utiliser le mode Spec-First ?

Utilisez le mode Spec-First si :

votre équipe travaille déjà principalement dans Git ;
vos contrats API sont relus en pull requests ;
vous voulez versionner OpenAPI à côté du code applicatif ;
vos ingénieurs préfèrent modifier YAML ou JSON directement ;
vous considérez la spec comme une source de vérité technique.

Choisissez plutôt le mode Design-First si :

vous voulez une interface guidée ;
des profils non techniques contribuent souvent à la conception ;
votre équipe préfère les formulaires visuels ;
vous voulez éviter l’édition manuelle du YAML.

Pour approfondir ce choix, consultez l’article comparatif.

Limitations et remarques sur la bêta

Le mode Spec-First est encore en bêta. À garder en tête :

les capacités peuvent évoluer ;
certains comportements peuvent changer selon les retours utilisateurs ;
GitHub et GitLab disposent d’intégrations directes ;
Azure DevOps passe par une connexion Git générique ;
il est préférable de tester d’abord sur un dépôt non critique.

Comme la spec est synchronisée avec un dépôt réel, appliquez les mêmes règles que pour votre code :

commitez intentionnellement ;
relisez les changements avant push ;
évitez les modifications non vérifiées sur une branche critique ;
utilisez l’annulation pour supprimer les expérimentations locales.

FAQ

Le mode Spec-First est-il gratuit ?

Le mode Spec-First est une fonctionnalité bêta dans Apidog. Son accès dépend de votre plan Apidog et du statut de disponibilité de la bêta. Le plus simple est de l’activer dans le module API et de vérifier 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 avec des identifiants Git standard.

D’autres hébergeurs Git peuvent fonctionner via cette connexion générique si le workflow repose sur Git standard.

Puis-je revenir au mode Design-First ?

Oui. Le bouton de changement de mode se trouve en bas à gauche du module API. Vous pouvez basculer entre Spec-First et Design-First selon le besoin du projet.

Quels formats de fichier puis-je modifier ?

Vous pouvez modifier des documents OpenAPI en :

YAML ;
JSON.

L’éditeur fournit la coloration syntaxique, la validation de schéma et l’auto-complétion pour OpenAPI et Swagger.

Qu’advient-il de mes modifications non poussées ?

Les modifications non poussées restent locales jusqu’au push. Le mode Spec-First les suit comme changements modifiés, ajoutés ou supprimés.

Si vous ne voulez pas conserver une modification, annulez-la avant de pousser. Elle n’entrera pas dans l’historique partagé.

Conclusion

Le mode Spec-First d’Apidog combine édition OpenAPI et synchronisation Git dans un même espace de travail. Vous modifiez la spec en YAML ou JSON, naviguez dans le document via un plan généré automatiquement, validez la structure en temps réel, puis commitez et poussez vers GitHub, GitLab ou Azure DevOps.

C’est une bêta, mais elle répond clairement à un cas d’usage : les équipes natives Git qui veulent traiter OpenAPI comme du code source. Pour l’essayer, activez le mode dans le module API, connectez un dépôt non critique, puis testez un cycle simple : édition, commit, push, synchronisation.

Quand vous êtes prêt, essayez le mode Spec-First dans la documentation et connectez-le à un dépôt adapté à votre workflow.

DEV Community