Comment versionner une spécification OpenAPI avec Git ?

Votre spécification OpenAPI est un contrat. Si elle dérive du code réel, les clients cassent, les mocks deviennent faux et les tests valident une API qui n’existe plus. Traitez donc openapi.yaml comme du code : versionnez-le dans Git, travaillez par branche, relisez les diffs et validez chaque changement en CI.

Essayez Apidog aujourd’hui

Ce guide montre comment mettre en place un workflow Git pour OpenAPI : où placer le fichier, comment nommer les branches, quoi vérifier dans une PR, comment pousser les changements depuis Apidog et quelles validations automatiser.

Pourquoi versionner votre spécification OpenAPI

Une spécification stockée dans un wiki ou un lecteur partagé n’a pas d’historique exploitable. Vous ne savez pas qui a modifié la payload de POST /orders, ni pourquoi.

Avec Git, vous obtenez immédiatement :

• Historique : chaque changement est un commit avec auteur, date et message.
• Blame : git blame openapi.yaml indique qui a ajouté un champ ou une contrainte.
• Rollback : une mauvaise fusion peut être annulée rapidement.
• Relecture : les changements de contrat passent par une pull request.

C’est la base d’un workflow API Git-natif : la spécification est du code source, donc elle vit dans Git.

Où placer le fichier OpenAPI dans le dépôt

Gardez une structure simple et prévisible. Pour un service unique, placez la spécification à la racine ou dans un dossier api/.

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

Si vous maintenez plusieurs versions majeures en parallèle, séparez-les par fichier :

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

Cette organisation isole les changements cassants :

• api-v1.yaml reste stable pour les clients existants.
• api-v2.yaml évolue avec les nouvelles ruptures de contrat.
• Les diffs restent plus courts et plus faciles à relire.

C’est le principe de l’API spec as code.

Documentez la convention dans le README.md. Évitez surtout d’avoir deux fichiers qui prétendent être “la” spécification officielle.

Stratégies de branches pour les changements de spécification

Vous n’avez pas besoin d’un modèle Git séparé pour OpenAPI. Réutilisez le workflow de votre code :

1. Créez une branche depuis main.
2. Modifiez la spécification.
3. Ouvrez une pull request.
4. Faites valider par la CI et par un reviewer.
5. Fusionnez.

Une convention de nommage rend les changements API plus visibles :

Type de branche	Modèle	Exemple
Nouveau endpoint	api/add-<ressource>	api/add-refunds
Modification de champ	api/change-<ressource>-<champ>	api/change-order-status
Changement cassant	api/breaking-<description>	api/breaking-v2-auth
Correction / nettoyage	api/fix-<description>	api/fix-pagination-schema

Le préfixe api/ indique immédiatement que la PR modifie le contrat. Le préfixe breaking- signale qu’une attention particulière est nécessaire, souvent avec une montée de version majeure.

Gardez les branches courtes. Une branche de spécification qui reste ouverte plusieurs semaines risque de créer des conflits avec les changements des autres équipes.

Relire une modification OpenAPI dans une pull request

Une PR de spécification est une modification de contrat. Elle doit être relue comme du code de production.

Écrivez le YAML pour qu’il soit lisible dans un diff :

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"

Bonnes pratiques de formatage :

• indentation cohérente ;
• une propriété par ligne ;
• pas de réorganisation inutile ;
• références $ref explicites ;
• noms de schémas stables.

Dans la PR, vérifiez surtout :

• Changements cassants : champ requis ajouté, champ supprimé, renommage, type modifié, valeur d’enum retirée.
• Rétrocompatibilité : les nouveaux champs optionnels et nouveaux endpoints sont généralement sûrs ; les modifications de structures existantes le sont moins.
• Cohérence de nommage : casse, pluriel, conventions REST, noms de paramètres.
• Complétude : summary, réponses succès, erreurs, schémas et exemples.
• Exemples : des exemples réalistes améliorent la documentation, les mocks et les tests.

Ne comptez pas uniquement sur la relecture humaine pour détecter les ruptures. Ajoutez un diff OpenAPI en CI pour comparer la PR avec main.

Commit et push depuis Apidog

Modifier le YAML à la main fonctionne, mais un éditeur visuel avec validation intégrée réduit les erreurs. Le mode Spec-First d’Apidog permet de synchroniser la spécification avec Git dans les deux sens.

Workflow typique :

1. Connectez votre dépôt Git dans Apidog.
2. Sélectionnez le fichier de spécification, par exemple api/openapi.yaml.
3. Modifiez les endpoints, schémas et exemples dans l’éditeur visuel.
4. Validez la spécification.
5. Committez sur une branche.
6. Poussez vers le dépôt.
7. Ouvrez la PR comme d’habitude.

Apidog sérialise le YAML de manière cohérente, ce qui limite les diffs bruyants dus au reformatage. La configuration complète est disponible dans la documentation du mode Spec-First d’Apidog. Pour un cas GitHub, consultez aussi la synchronisation de votre spécification OpenAPI vers GitHub.

Ajouter une validation OpenAPI en CI

Ne laissez pas une spécification invalide atteindre main. Ajoutez une validation dans vos checks de pull request.

Exemple minimal avec GitHub Actions :

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

Ensuite, ajoutez progressivement :

• lint de style et de structure ;
• validation OpenAPI 3.x ;
• comparaison avec main ;
• détection de changements cassants ;
• blocage de la PR si un changement incompatible est détecté.

Exemple de logique attendue :

PR branch openapi.yaml
        │
        ▼
lint OpenAPI
        │
        ▼
compare with main
        │
        ▼
fail if breaking change

Ces checks s’exécutent rapidement et attrapent des erreurs faciles à manquer en relecture manuelle.

Bonnes pratiques pour versionner OpenAPI

Appliquez ces règles pour garder un workflow fiable :

• Utilisez le versionnement sémantique : mettez à jour info.version.
  • changement cassant : nouvelle majeure ;
  • ajout rétrocompatible : nouvelle mineure ;
  • correction de documentation : patch.
• Tenez un changelog : ajoutez un CHANGELOG.md à côté de la spécification.
• Livrez de petits diffs : une modification logique par PR.
• Écrivez des commits descriptifs : Ajouter refundReason à la demande de remboursement est plus utile que update spec.
• Ne modifiez jamais directement main : même pour une faute de frappe, passez par une branche.
• Automatisez la validation : lint, parsing OpenAPI et détection de ruptures.
• Évitez les reformattages globaux : ils rendent les diffs inutilisables.

Checklist de PR OpenAPI

Avant de demander une relecture, vérifiez :

• [ ] Le fichier modifié est le bon fichier de spécification.
• [ ] Le YAML est valide.
• [ ] Les nouveaux endpoints ont un summary.
• [ ] Les réponses succès et erreur sont documentées.
• [ ] Les schémas référencés existent.
• [ ] Les champs requis sont justifiés.
• [ ] Les exemples sont réalistes.
• [ ] info.version est mis à jour si nécessaire.
• [ ] Le changelog est mis à jour si nécessaire.
• [ ] La CI passe.

FAQ

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

Exécutez un outil de diff OpenAPI en CI qui compare la version de la PR avec celle de main. Des outils comme oasdiff classent les changements comme cassants, non cassants ou non classifiés, et peuvent faire échouer la build si une rupture est détectée.

Cela permet d’identifier automatiquement :

• champs supprimés ;
• nouveaux paramètres requis ;
• types modifiés ;
• valeurs d’enum retirées ;
• réponses supprimées ou renommées.

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

Commencez avec un seul fichier openapi.yaml. C’est plus simple à relire, valider et versionner.

Divisez seulement lorsque :

• la spécification devient trop volumineuse ;
• vous maintenez plusieurs versions majeures ;
• certains schémas sont partagés ;
• les PR deviennent difficiles à relire.

Dans ce cas, utilisez des fichiers par version (api-v1.yaml, api-v2.yaml) ou des $ref vers des fichiers séparés. Ne divisez pas trop tôt : un fichier clair vaut mieux que plusieurs fichiers fragmentés.

Puis-je versionner ma spécification sans écrire le YAML à la main ?

Oui. Le mode Spec-First d’Apidog permet de modifier la spécification dans un éditeur visuel, puis de synchroniser les changements avec Git. Vous gardez l’historique, les branches, les commits et les pull requests, tout en évitant une partie des erreurs liées à l’édition manuelle du YAML.