01
Respecter le sens ancien vers nouveau
Le risque concerne les consommateurs de l’ancien contrat. Inverser les deux entrées affiche d’abord un aperçu et permet ensuite une restauration unique.
Contrats API
diff OpenAPIExaminer avant la publication
Collez la version ancienne et la nouvelle, puis lancez la comparaison.
diff OpenAPI
Ancienne spécification
Nouvelle spécification
Rapport de changements
Les deux spécifications restent dans ce navigateur ; aucune requête API n’est envoyée.
Options de comparaison
Portée : opérations, paramètres, corps de requête et réponses suivis. Pas de preuve de compatibilité réelle.
Collez les deux spécifications pour comparer.
Un diff OpenAPI aide à préparer une livraison quand des clients utilisent déjà le contrat précédent. Une différence de texte ne dit pas clairement si une route supprimée ou un paramètre devenu obligatoire va casser ces clients.
Vous pouvez comparer les spécifications OpenAPI sans compte. La comparaison de contrats API classe les changements incertains à vérifier au lieu de promettre une compatibilité que le document seul ne prouve pas.
Pourquoi utiliser ce diff OpenAPI
Partir du contrat utilisé par les clients
Le diff OpenAPI lit l’ancien document vers le nouveau. La disparition d’un champ de réponse et l’ajout d’une route restent deux constats distincts, avec un risque différent.
Tracer les exclusions exactes
Un chemin saisi à l’identique est retiré des deux versions et conservé dans la liste des exclusions du rapport. Le périmètre de la revue reste vérifiable.
Trois points à vérifier avant le rapport
02
Saisir un chemin complet par ligne
/internal/health désigne une clé path OpenAPI exacte, ni une expression régulière ni un JSON Pointer. Toute modification rend le rapport précédent obsolète.
03
Distinguer filtre et export
Le filtre réduit seulement les lignes visibles. Les téléchargements JSON et Markdown gardent toutes les constatations fraîches et les chemins exclus.
Les changements du contrat examinés
Opérations et méthodes
Une route ou une méthode supprimée fait partie des changements incompatibles possibles. Une nouvelle opération figure à part dans le rapport.
Entrées et réponses
Les paramètres rendus obligatoires, champs requis, réponses supprimées et champs de réponse perdus sont signalés. Les types et enum simples sont inspectés si les références locales se résolvent.
Preuves exportables
Chaque ligne conserve méthode, chemin, règle et valeurs avant/après. Le rapport intégral est disponible en JSON ou Markdown uniquement après une comparaison complète.
Ce que la comparaison statique ne conclut pas
- Aucune récupération distante
- Collez du JSON ou du YAML : l’outil ne charge pas d’URL de schéma, n’appelle pas l’API et ne téléverse pas vos documents.
- Exclusions exactes seulement
- Ni joker, ni regex, ni chemins de callback ne sont pris en charge pour exclure des opérations.
- Références incomplètes bloquantes
- Un $ref externe, un dialecte non pris en charge, un webhook ou un callback empêchent la création d’un rapport de risque complet.
- Pas de preuve de compatibilité réelle
- Les ruptures de compatibilité dépendent aussi du serveur et des clients. Vérifiez les consommateurs avant une mise en production.
Questions fréquentes sur le diff OpenAPI
Quels formats de schémas sont supportés ?
Swagger 2.0 et OpenAPI 3.0/3.1 sont acceptés en JSON ou YAML. Les collections Postman et les contrats GraphQL ne font pas partie de cette comparaison.
Qu'est-ce qu'un 'breaking change' (changement incompatible) ?
Un changement incompatible peut rendre invalide un appel conforme à l’ancien contrat : route retirée, entrée devenue obligatoire ou réponse attendue supprimée. Le diff OpenAPI signale des risques, pas une certitude d’exécution.
L'outil peut-il détecter le type de schéma automatiquement ?
Oui. Le parseur reconnaît JSON et YAML à partir du texte. Une erreur de syntaxe indique le côté et, si disponible, la ligne et la colonne.
Que contient le rapport d'impact ?
Le rapport d’impact contient la catégorie, la règle, la méthode, le chemin, le pointeur et les valeurs avant/après. Les changements complexes restent à examiner.
Mes schémas d'API sont-ils stockés ?
Non. Les schémas restent dans le navigateur pour cette session. Aucun historique ni lien partagé n’est créé; exportez vous-même le rapport si vous souhaitez l’archiver.
Cette comparaison vous a-t-elle aidé ?
Lancer un diff OpenAPI avant la livraison
Un diff OpenAPI fournit des constats vérifiables et signale ses limites. Confirmez les cas critiques avec vos tests consommateurs.