Diff OpenAPI fiable: la base de l’automatisation
Le contrat OpenAPI doit vivre dans le repo, pas dans un wiki ni dans une console fournisseur. Un document OpenAPI décrit les chemins, opérations, paramètres, corps, réponses et schémas JSON exposés aux clients (source: OpenAPI Initiative — OpenAPI Specification 3.1.0 (consulté 2026-07)).
Versionner le contrat avec le code
Placez le fichier openapi.yaml ou openapi.json dans le dépôt applicatif. La CI compare uniquement ce fichier entre HEAD et main, ce qui rend le diff reproductible sur chaque pull request.
Classer le diff avec oasdiff
Exécutez oasdiff entre la spec de main et celle du commit courant. L’outil compare des spécifications OpenAPI et signale les changements incompatibles ou compatibles (source: Tufin — oasdiff (OpenAPI Diff) GitHub repository (consulté 2026-07)).
Traduire le diff en SemVer
Mappez breaking vers major, ajout compatible vers minor, correction compatible vers patch. SemVer définit ces incréments autour de la compatibilité de l’API publique (source: Semantic Versioning — Spécification SemVer 2.0.0 (consulté 2026-07)).
Ignorez les changements purement descriptifs: summary, description, exemples, tags ou ordre de champs sans impact contractuel. Mettez ces ignores dans un fichier versionné, sinon un renommage de phrase peut bloquer une PR.
Émettez un artefact diff-openapi.json. Ce fichier sert de source commune pour le commentaire de PR, les release notes et le portail de documentation, sans relancer la comparaison ni réinterpréter la spec.
Changelogs lisibles générés à la volée (PR et releases)
Un changelog automatique devient lisible quand un signal contrat et un signal commit alimentent le générateur: le diff OpenAPI décrit le changement d’API; Conventional Commits qualifie l’intention avec des types comme feat, fix ou chore (source: Conventional Commits 1.0.0 (consulté 2026-07)). La sortie doit garder l’impact API et la raison du changement.
Groupez chaque entrée par chemin et verbe HTTP, puis classez-la sous Ajouts, Modifications, Suppressions ou Deprecations. Exemple: POST /invoices va dans Ajouts pour un nouveau corps de requête; GET /users/{id} va dans Deprecations pour un champ marqué obsolète.
Le job CI publie en commentaire de PR un résumé avec endpoints touchés et niveau SemVer proposé. Le Markdown complet reste joint comme artefact de workflow, un cas supporté par GitHub Actions pour conserver les fichiers produits par un run (source: GitHub Actions — Documentation officielle (consulté 2026-07)).
Au moment du tag, attachez le Markdown de changelog à la release et générez changelog.json. Ce JSON expose version, date, endpoints, method, category, commitRefs et breaking, pour permettre aux SDK, portails développeurs ou clients internes de filtrer les changements.
Bloquer les breaking changes non signalés avant merge
Le job CI compare l’OpenAPI de la branche avec la spécification de référence, puis échoue si oasdiff marque un changement comme breaking sans label explicite, par exemple api-breaking-approved (source: Tufin — oasdiff (OpenAPI Diff) GitHub repository (consulté 2026-07)). La protection de branche doit exiger ce job avant merge, via les checks obligatoires du dépôt (source: GitHub Actions — Documentation officielle (consulté 2026-07)).
Un endpoint supprimé, un champ requis ajouté ou un type de réponse modifié doit bloquer la PR tant qu’un humain n’a pas validé l’impact.
Le même job vérifie le bump de version. Si un breaking est présent, la version proposée doit passer en MAJOR selon SemVer, car une incompatibilité d’API publique impose un incrément majeur (source: Semantic Versioning — Spécification SemVer 2.0.0 (consulté 2026-07)).
Ajoutez un commentaire automatique dans la PR avec trois champs obligatoires: endpoints impactés, consommateurs connus, plan de migration. Dès qu’un breaking candidat apparaît, envoyez aussi un message Slack ou Webhook avec le lien PR, le diff OpenAPI et le statut du label d’approbation.
Publier des artefacts vivants: schémas, diff et changelog JSON
Publiez les artefacts comme des contrats, pas comme des logs de CI. Chaque release doit produire une spec OpenAPI, un diff JSON et un changelog JSON sous une URL immuable dans un bucket ou un registry.
| Artefact | URL versionnée | Usage |
|---|---|---|
| Spec OpenAPI | openapi/{version}/openapi.json | Contrat consommé par tests, docs et générateurs SDK |
| Diff JSON | diff/{from}..{to}.json | Preuve machine des changements entre deux releases |
| Changelog JSON | changelog/{version}.json | Source structurée pour portails, SDK et flux RSS |
Exposez aussi /changelog.json dans la documentation publique. Ce fichier sert de point d’entrée stable aux portails développeurs, générateurs de SDK et agrégateurs RSS, sans parser du Markdown.
Pour les environnements privés, signez les objets ou imposez une authentification au niveau du bucket, du registry ou du CDN. Ajoutez Cache-Control: immutable sur les URL versionnées et Cache-Control: no-cache sur les alias mobiles.
Chaque SDK ou client généré doit embarquer l’URL du changelog correspondant à sa version. Placez-la dans les métadonnées du package, la doc générée et les notes de release pour tracer quel client dépend de quel contrat publié.
Workflow CI prêt à copier (GitHub Actions / GitLab)
Comparer la PR à main
Déclenchez le job sur PR, puis exécutez: checkout, installation de oasdiff, comparaison main..PR, écriture de diff.json et changelog.md. oasdiff cible les différences OpenAPI et fournit une sortie exploitable en CI (source: Tufin — oasdiff (OpenAPI Diff) GitHub repository (consulté 2026-07)).
Publier et bloquer
Publiez diff.json et changelog.md comme artefacts, puis ajoutez le résumé en commentaire de PR. Côté GitHub, marquez ce job comme required dans la protection de branche; le merge attendra son statut vert (source: GitHub Actions — Documentation officielle (consulté 2026-07)).
Relancer seulement quand l’état utile change
Ajoutez concurrency avec une clé par PR pour annuler les runs obsolètes. Déclenchez aussi sur labeled et unlabeled, puis conditionnez le blocage à vos labels, par exemple breaking-change-accepted (source: GitHub Actions — Documentation officielle (consulté 2026-07)).
Valider au tag
Sur création de tag, relancez le diff entre la dernière release et le tag courant. Vérifiez que l’incrément SemVer correspond au diff: MAJOR pour rupture, MINOR pour ajout compatible, PATCH pour correction compatible (source: Semantic Versioning — Spécification SemVer 2.0.0 (consulté 2026-07)). Attachez changelog.md à la release et poussez changelog.json dans le registre d’artefacts.
Dans GitLab CI, gardez le même découpage: comparaison en merge request, publication des artefacts, puis job obligatoire avant merge.
Continue reading
Comment générer automatiquement des docs à partir du code — CI
Un plan technique prêt à brancher: structure de repo, specs API, pipeline CI/CD, préviews de PR et garde-fous pour des docs toujours à jour.
Meilleures alternatives à Kapa.ai pour les entreprises
Un plan court et actionnable pour sélectionner une alternative à Kapa.ai côté entreprise: matrice d’architecture, shortlist par cas d’usage, tests, contrat et mise en prod.
Guide pour choisir une alternative à Mintlify sans regret
Un cadre concret pour comparer GitBook, Docusaurus et co., estimer le TCO, et planifier une migration de docs sans perte de SEO ni de workflow.