Comment versionner une spécification OpenAPI avec Git ?

Votre spécification OpenAPI est un contrat. Lorsque des dérives se produisent, les clients sont cassés, les maquettes deviennent obsolètes et les tests sont effectués sur une API qui n'existe plus. Traitez donc la spécification comme le reste de votre code : mettez-la dans Git, branchez-la, examinez-la et validez-la à chaque modification.

Ce guide vous expliquera le contrôle de version OpenAPI avec Git de A à Z. Où le fichier réside, comment brancher, ce que les réviseurs recherchent réellement dans un diff de spécification, et comment pousser les changements directement depuis Apidog. À la fin, vous aurez un workflow auquel toute votre équipe pourra faire confiance.

Pourquoi contrôler la version de votre spécification OpenAPI

Une spécification stockée dans un wiki ou un lecteur partagé n'a pas d'historique. Vous ne pouvez pas voir qui a modifié la charge utile du POST /orders mardi dernier, ni pourquoi. Git résout ce problème.

Mettez openapi.yaml sous contrôle de version et vous obtenez quatre choses gratuitement :

• Historique. Chaque modification est un commit avec un auteur, un horodatage et un message.
• Blâme. git blame openapi.yaml vous dit qui a ajouté ce champ obligatoire et quand.
• Retour arrière. Une mauvaise fusion qui a rompu le contrat ? Annulez le commit et vous revenez à une spécification fonctionnelle.
• Relecture. Les modifications de spécification passent par des pull requests, de sorte qu'une deuxième personne voit le diff avant qu'il ne soit déployé.

C'est le fondement d'un workflow API Git-natif : la spécification est du code source, et le code source vit dans Git.

Où le fichier de spécification réside dans le dépôt

Gardez les choses simples et prévisibles. La plupart des équipes placent un seul fichier openapi.yaml à la racine du dépôt ou dans un dossier api/ :

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

Lorsque vous maintenez plusieurs versions majeures en parallèle, divisez par version avec un fichier par majeure :

api/
├── api-v1.yaml
└── api-v2.yaml

Cela permet d'isoler les changements cassants. api-v1.yaml reste gelé pour les clients existants tandis que api-v2.yaml évolue. Cela rend également les diffs plus petits et la relecture plus rapide, car chaque fichier change pour une seule raison. Traiter la spécification de cette manière est l'idée centrale derrière l'API spec as code.

Choisissez une convention et documentez-la. Le pire résultat est d'avoir deux fichiers prétendant être "la" spécification.

Stratégies de branching pour les modifications de spécification

Vous n'avez pas besoin d'un modèle de branchement spécial pour les spécifications. Réutilisez ce que votre code fait déjà. Créez une branche à partir de main, effectuez la modification, ouvrez une PR.

Convention de nommage qui permet de scanner facilement les branches de spécification :

Le préfixe api/ signale d'un coup d'œil "cette PR touche le contrat". Les réviseurs et la CI peuvent filtrer dessus. Pour les changements cassants, le préfixe explicite breaking- est un drapeau indiquant que cela nécessite une attention particulière et probablement une augmentation de version.

Gardez les branches de courte durée. Une branche de spécification qui vit pendant deux semaines entrera en conflit avec les changements de tout le monde. Les branches petites et ciblées se fusionnent proprement.

Revoir les modifications de spécification dans une pull request

C'est là que le contrôle de version prend tout son sens. Une PR de spécification est un changement de contrat, et les changements de contrat méritent une vraie relecture.

Écrivez le YAML d'une manière compatible avec les diffs afin que les réviseurs puissent lire le changement, et non se battre avec le formatage :

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

Une indentation cohérente et une propriété par ligne signifient qu'un ajout de champ unique apparaît comme un diff d'une seule ligne. C'est l'objectif.

Ce que les réviseurs devraient vérifier :

• Changements cassants. Un champ obligatoire a-t-il été ajouté à une requête ? Un champ de réponse a-t-il été supprimé ou renommé ? Une énumération a-t-elle perdu une valeur ? Chacun peut casser les clients existants.
• Rétrocompatibilité. Les nouveaux champs optionnels et les nouveaux endpoints sont sûrs. Les modifications des formes existantes ne le sont pas.
• Nommage et cohérence. Le nouveau endpoint correspond-il à la casse et à la pluralisation du reste de l'API ?
• Complétude. Chaque nouvelle opération nécessite un summary, des schémas de réponse et des réponses d'erreur.
• Exemples. Des exemples réalistes rendent la documentation et les maquettes utiles.

Pour la détection des changements cassants, appuyez-vous sur les outils plutôt que sur l'œil humain. Une étape CI (couverte ci-dessous) peut comparer la spécification de la PR avec main et faire échouer la build si elle détecte un changement incompatible. Les humains les manquent ; les outils de diff non.

Commit & push depuis Apidog

Modifier le YAML brut à la main fonctionne, mais un éditeur visuel avec validation en direct est plus rapide et détecte les erreurs plus tôt. Le mode Spec-First d'Apidog vous offre une synchronisation Git bidirectionnelle : modifiez la spécification dans l'interface utilisateur, commitez et poussez vers votre dépôt sans quitter l'outil. Récupérez les modifications d'un coéquipier de la même manière.

Le flux ressemble à ceci :

1. Connectez votre dépôt Git et dirigez Apidog vers le fichier de spécification.
2. Modifiez les endpoints, les schémas et les exemples dans l'éditeur visuel.
3. Apidog écrit un YAML propre et compatible avec les diffs dans le fichier.
4. Committez sur une branche et poussez, puis ouvrez votre PR comme d'habitude.

Parce qu'Apidog sérialise le YAML de manière cohérente, vos diffs restent petits et lisibles, sans réorganisation ou reformatage bruyants. Vous pouvez lire la configuration complète dans la documentation du mode Spec-First d'Apidog. Si vous souhaitez que le fichier soit placé chez un fournisseur spécifique, consultez la synchronisation de votre spécification OpenAPI vers GitHub.

Hooks de validation CI

Ne laissez jamais une spécification invalide atteindre main. Intégrez la validation dans vos vérifications de pull request afin qu'un contrat cassé fasse échouer la build automatiquement.

Une étape GitHub Actions minimale :

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Ajoutez plus de vérifications à mesure que vous évoluez :

• Lint la spécification pour les problèmes structurels et de style.
• Validez qu'elle est parsable comme OpenAPI 3.x légal.
• Effectuez un diff avec main pour détecter les changements cassants et les signaler dans la PR.

Ces vérifications s'exécutent en quelques secondes et détectent les erreurs qu'un réviseur humain pourrait ignorer.

Bonnes pratiques

Quelques habitudes pour maintenir un contrôle de version sain de la spécification au fil du temps :

• Utilisez le versionnement sémantique. Augmentez le champ info.version. Un changement cassant signifie une nouvelle majeure ; les ajouts rétrocompatibles augmentent la mineure.
• Tenez un changelog. Un court fichier CHANGELOG.md à côté de la spécification indique aux consommateurs ce qui a changé entre les versions.
• Livrez de petits diffs. Un changement logique par PR. Les grandes PR de spécification cachent les changements cassants dans le bruit.
• Rédigez des messages de commit descriptifs. "Ajouter refundReason à la demande de remboursement" est mieux que "mettre à jour la spécification".
• Ne jamais modifier la spécification fusionnée directement sur main. Toujours créer une branche, même pour une faute de frappe.

FAQ

Comment détecter les changements cassants dans une spécification OpenAPI ?

Exécutez un outil de diff de spécification en CI qui compare la pull request à la version sur main. Des outils comme oasdiff classent chaque changement comme cassant, non-cassant ou non classifié, et peuvent faire échouer la build en cas de changement cassant. Cela détecte les champs supprimés, les nouveaux paramètres requis et les types modifiés qu'une révision manuelle pourrait manquer.

Dois-je garder un seul fichier OpenAPI ou le diviser en plusieurs ?

Commencez avec un seul fichier openapi.yaml. C'est le plus facile à examiner et à versionner. Lorsque le fichier devient volumineux ou que vous maintenez plusieurs versions majeures en parallèle, divisez par version majeure (api-v1.yaml, api-v2.yaml) ou utilisez $ref pour diviser les schémas en fichiers séparés. Ne divisez pas prématurément ; un fichier lisible vaut mieux que cinq fichiers fragmentés.

Puis-je contrôler la version de ma spécification sans écrire le YAML à la main ?

Oui. Le mode Spec-First d'Apidog vous permet de modifier la spécification dans un éditeur visuel et de synchroniser les changements avec Git dans les deux sens. Il écrit un YAML cohérent, de sorte que vos diffs restent propres et vos pull requests lisibles, tout en bénéficiant d'un historique et d'une révision Git complets.