Votre code vit dans Git. Vos pipelines CI, vos revues et l'historique de vos versions vivent dans Git. Alors pourquoi la spécification de votre API vivrait-elle ailleurs ?
Un workflow API natif Git conserve votre définition OpenAPI au même endroit que votre code. Vous modifiez la spécification en tant que simple fichier YAML ou JSON, la commitez, et la faites passer par le même processus de revue que vous utilisez pour tout le reste. Pas de base de données cloud séparée. Pas de danse export-import. La spécification est juste un autre fichier dans votre dépôt.
Ce qu'est un workflow API natif Git
Un workflow API natif Git traite votre spécification API comme du code. Le fichier OpenAPI se trouve dans un dépôt à côté de vos services. Chaque modification est un commit. Chaque commit a un auteur, un message et un diff.
Cela vous donne trois choses que vous attendez déjà du code source :
- Historique des versions. Vous pouvez voir qui a modifié un endpoint et quand.
git blamefonctionne sur votre spécification. - Branchement et revue. Les modifications de spécification passent par des pull requests. Les relecteurs voient le diff exact avant toute fusion.
- Une source unique de vérité. Le fichier dans
mainest le contrat. Les outils, la documentation et les mocks lisent tous à partir de celui-ci.
C'est l'idée centrale derrière un workflow API "spec-first" : la spécification mène, et l'implémentation suit. Pour un aperçu plus approfondi de cette pratique, consultez notre guide sur le développement API "spec-first".
L'approche inverse stocke votre spécification dans une application cloud propriétaire. Cela fonctionne jusqu'à ce que votre équipe grandisse ou que votre processus mûrisse. Ensuite, les failles apparaissent.
Le problème des spécifications API bloquées dans le cloud
La plupart des outils de conception d'API conservent la spécification dans leur propre base de données. Vous l'éditez via leur interface utilisateur. Le "fichier" que vous pensez posséder est en réalité une ligne dans le système de quelqu'un d'autre.
Cela se décompose de manière prévisible.
La revue se fait à deux endroits. Les modifications de code passent par GitHub. Les modifications de spécification passent par un outil distinct avec ses propres commentaires et son propre historique. Les relecteurs changent de contexte. Les approbations se désynchronisent.
Le diff est masqué. Lorsque la spécification vit dans une base de données cloud, vous ne pouvez pas voir un diff propre ligne par ligne dans votre pull request. Vous approuvez une "v3 du design" sans savoir ce qui a réellement changé.
L'exportation devient une corvée. Pour intégrer la spécification dans la CI, vous l'exportez, commitez l'exportation et espérez que personne n'a modifié la copie cloud entre-temps. Deux sources de vérité, un conflit inévitable.
L'automatisation vous combat. Les linters, les tests de contrat et les générateurs de code veulent un fichier sur le disque. Une spécification bloquée dans le cloud force une étape de récupération avant que tout cela ne s'exécute.
Traiter votre spécification API comme du code supprime tout cela. Le fichier est la spécification. Git est l'historique. Votre pipeline existant fait le reste. Nous couvrons le principe en détail dans la spécification API en tant que code.
Comment fonctionne le mode Spec-First d'Apidog
Le mode Spec-First est conçu pour les équipes qui pensent déjà en commits et en branches. Vous concevez l'API sous forme de fichiers YAML ou JSON bruts, et Apidog maintient ces fichiers synchronisés avec votre dépôt Git dans les deux sens.
Voici ce que vous obtenez.
Un éditeur OpenAPI de style IDE
Vous écrivez la spécification dans un éditeur de code, et non dans un formulaire. L'éditeur apporte les commodités que vous attendez d'un IDE :
- Mise en évidence syntaxique pour YAML et JSON.
- Validation par rapport aux schémas OpenAPI et Swagger, de sorte que les erreurs apparaissent au fur et à mesure que vous tapez.
- Complétion automatique pour les mots-clés, types et références OpenAPI.
Vous gardez le contrôle du fichier exact. Pas de champs cachés, pas de métadonnées uniquement pour l'interface utilisateur.
Fichiers YAML/JSON bruts
La spécification est un vrai fichier. Un petit extrait :
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
C'est le fichier qui arrive dans votre dépôt. Ce que vous éditez est ce qui est commité.
Une arborescence navigable auto-analysée
Au fur et à mesure que vous tapez, Apidog analyse le fichier et construit une arborescence visuelle dans la barre latérale gauche. Les chemins, les opérations et les schémas apparaissent sous forme d'arborescence que vous pouvez parcourir. Vous obtenez la lisibilité d'un outil de conception et la précision des fichiers bruts en même temps.
Les spécifications longues restent navigables. Accédez à un endpoint sans faire défiler des centaines de lignes.
Synchronisation Git bidirectionnelle
Le mode Spec-First se connecte à votre fournisseur Git et synchronise les modifications dans les deux sens. Il prend en charge GitHub et GitLab directement, et Azure DevOps via une connexion Git.
Tirez les modifications que vos coéquipiers ont poussées. Modifiez localement dans l'éditeur Apidog. Puis commitez et poussez vers la même branche. Le dépôt et votre espace de travail restent alignés.
Commit, push et un indicateur d'état de synchronisation
Vous ne quittez pas Apidog pour gérer Git. Stagiapez vos modifications, écrivez un message de commit et poussez. Un indicateur d'état de synchronisation vous indique où vous en êtes. Après un push réussi, il affichera quelque chose comme "Synchronisé à l'instant". Si vous changez d'avis avant de pousser, vous pouvez annuler les modifications non poussées et revenir à l'état synchronisé précédent.
Cette synchronisation bidirectionnelle est au cœur du workflow API natif Git. Pour une démonstration détaillée du côté GitHub, consultez la synchronisation de la spécification OpenAPI vers GitHub.
Guide de configuration
Voici comment passer d'un dépôt vide à une spécification synchronisée. La référence complète se trouve dans la documentation du mode Spec-First.
- Créez un projet à partir d'un dépôt. Dans Apidog, démarrez un nouveau projet Spec-First et connectez votre fournisseur Git. Choisissez le dépôt qui contient votre spécification API et sélectionnez la branche à suivre, généralement
main. Apidog récupère les fichiers de spécification existants dans l'éditeur.
- Éditez la spécification. Ouvrez le fichier OpenAPI dans l'éditeur. Ajoutez un endpoint, ajustez un schéma ou corrigez une réponse. La mise en évidence syntaxique, la validation et l'auto-complétion vous guident pendant que vous écrivez. L'arborescence de la barre latérale gauche se met à jour à mesure que le fichier change.
- Suivez les fichiers modifiés, ajoutés et supprimés. Apidog montre quels fichiers vous avez modifiés depuis la dernière synchronisation. Les fichiers modifiés, ajoutés et supprimés sont signalés afin que vous sachiez exactement ce qui va être inclus dans le commit.
- Rédigez un message de commit. Décrivez le changement en langage clair, de la même manière que vous le feriez dans n'importe quel client Git. "Ajouter une réponse 404 à getOrder" est mieux que "mettre à jour la spécification".
- Poussez. Envoyez le commit à la branche suivie. Vos coéquipiers et votre pipeline CI voient maintenant la nouvelle version.
- Vérifiez "Synchronisé à l'instant". Observez l'indicateur d'état de synchronisation confirmer le push. Lorsqu'il affiche "Synchronisé à l'instant", vos modifications locales et la branche distante correspondent. À partir de là, le changement passe par votre processus normal de pull request et de révision.
C'est la boucle complète : tirer, éditer, committer, pousser, vérifier. Pas d'étape d'exportation. Pas de deuxième source de vérité.
Mode "Spec-First" vs Mode "Design-First"
Apidog prend en charge deux façons de travailler. La différence réside dans l'emplacement de la spécification et la manière dont vous l'éditez.
| Mode Spec-First (bêta) | Mode Design-First | |
|---|---|---|
| Stockage des spécifications | Fichiers YAML/JSON bruts dans Git | Projet cloud Apidog |
| Éditeur principal | Éditeur de code de style IDE | Interface utilisateur visuelle basée sur des formulaires |
| Contrôle de version | Git natif (commits, branches, diffs) | Historique et branches Apidog |
| Synchronisation Git bidirectionnelle | Oui (GitHub, GitLab, Azure DevOps) | Via export/import |
| Idéal pour | Équipes qui vivent dans Git | Équipes qui préfèrent un workflow visuel |
Aucun mode n'est "meilleur". Ils répondent à des habitudes différentes. Si votre processus de revue et de publication fonctionne déjà sur Git, le mode Spec-First élimine la couture. Si votre équipe conçoit visuellement et touche rarement à l'OpenAPI brut, le mode Design-First peut mieux convenir.
Quand l'utiliser
Optez pour le mode Spec-First lorsque :
- Votre spécification doit passer par des pull requests et une revue de code.
- Vous voulez
git blameet un véritable historique de commits sur votre contrat API. - Votre CI exécute des linters de spécification, des tests de contrat ou de la génération de code qui nécessitent un fichier sur le disque.
- Plusieurs ingénieurs éditent la spécification et vous voulez des diffs propres et fusionnables.
- Vous en avez assez d'exporter d'un outil pour alimenter un autre.
Restez avec une approche visuelle et cloud-first lorsque votre équipe conçoit des API sans écrire d'OpenAPI brut, ou lorsque des non-ingénieurs sont propriétaires de la spécification et préfèrent un éditeur basé sur des formulaires.
FAQ
Qu'est-ce qu'un workflow API natif Git ?
Un workflow API natif Git stocke votre spécification OpenAPI en tant que fichier dans un dépôt Git et gère chaque modification via des commits, des branches et des pull requests. La spécification suit le même processus de revue et de contrôle de version que le code de votre application, il n'y a donc qu'une seule source de vérité.
Le mode Spec-First d'Apidog prend-il en charge GitHub et GitLab ?
Oui. Le mode Spec-First se synchronise de manière bidirectionnelle directement avec GitHub et GitLab. Azure DevOps est pris en charge via une connexion Git. Vous connectez le dépôt, choisissez une branche, et Apidog maintient vos modifications et le dépôt distant synchronisés.
Puis-je éditer des fichiers OpenAPI en tant que YAML ou JSON bruts ?
Oui. Le mode Spec-First vous offre un éditeur de style IDE pour le YAML et le JSON bruts, avec la mise en évidence syntaxique, la validation de schéma et l'auto-complétion pour OpenAPI et Swagger. Une arborescence dans la barre latérale gauche analyse automatiquement le fichier afin que vous puissiez naviguer rapidement dans de grandes spécifications.
Quelle est la différence entre le mode Spec-First et le mode Design-First ?
Le mode Spec-First conserve votre spécification sous forme de fichiers dans Git et les édite dans un éditeur de code avec une synchronisation bidirectionnelle. Le mode Design-First conserve la spécification dans un projet cloud Apidog avec un éditeur visuel basé sur des formulaires. Choisissez le mode Spec-First si votre workflow fonctionne déjà avec Git.
Conclusion
Un workflow API natif Git met fin à la séparation entre votre code et votre contrat API. La spécification devient un fichier, le fichier devient un commit, et le commit passe par le processus de revue auquel vous faites déjà confiance.
Le mode Spec-First d'Apidog vous offre l'éditeur de style IDE, l'arborescence navigable et la synchronisation Git bidirectionnelle pour concrétiser cela. Vous éditez du YAML ou du JSON brut, commitez un message clair, poussez, et voyez le statut afficher "Synchronisé à l'instant".
Essayez le mode Spec-First et ramenez votre spécification API à la maison dans Git.