Collez les définitions avant et après pour produire un rapport. Confirmez l’impact client par des tests de contrat ; les références externes ne sont pas récupérées.
Fonctionne localement dans votre navigateurLes étiquettes de modification avec rupture se concentrent sur les opérations supprimées, les réponses supprimées et les entrées nouvellement requises. Les modifications du schéma sont marquées pour examen car la compatibilité dépend de vos clients.
Utilisez cette différence comme examen rapide du contrat, puis confirmez l'impact sur le consommateur dans les tests API versionnés. Les références externes et les fichiers distants ne sont pas résolus par ce vérificateur local.
Collez la spécification publiée dans « Earlier specification », la proposition dans « Updated specification », puis cliquez sur Comparer les spécifications. Les deux champs acceptent JSON ou YAML, et les deux documents restent dans le navigateur : rien n’est envoyé, récupéré ni exécuté.
Le résultat est un rapport de revue classé par gravité, avec un JSON Pointer pour chaque entrée, ce qui permet de remonter chaque constat jusqu’à l’endroit exact du nouveau document.
Une opération supprimée, un paramètre obligatoire supprimé, un paramètre optionnel devenu obligatoire, un paramètre obligatoire ajouté et un corps de requête devenu obligatoire sont listés en DANGER. De même qu’un code de réponse supprimé et un type de contenu de requête supprimé, car des clients existants peuvent en dépendre.
Les modifications de schéma sont signalées en WARNING et non en DANGER, car la rupture dépend du client : schémas de paramètre, de requête et de réponse modifiés, schémas de composant supprimés ou modifiés, et paramètres optionnels supprimés. La modification d’un composant partagé est signalée sous /components/schemas/<nom>, là où une définition générée porte le plus souvent son changement majeur.
Lors de la comparaison des schémas, les mots-clés required, enum, type, allOf, anyOf et oneOf sont traités comme des ensembles : un document régénéré qui ne fait que les réordonner n’est pas signalé comme modifié.
Les opérations sont appariées par méthode et par chemin. Un paramètre de chemin renommé apparaît donc comme une opération supprimée plus une opération ajoutée, et non comme une modification unique. Les références internes au même document (#/components/...) sont résolues avant la comparaison ; les références externes et distantes ne sont pas récupérées, un paramètre ou un schéma présent uniquement dans un autre fichier est donc comparé tel qu’il est écrit.
Les documents Swagger 2.0 sont comparés de la même façon, car chemins, opérations, paramètres et réponses sont lus de la même manière. Les servers, exigences de sécurité, tags, descriptions et exemples ne sont pas comparés.
Chaque entrée porte une gravité (DANGER, WARNING, INFO ou GOOD), le JSON Pointer de l’élément concerné et une phrase décrivant le changement. Dans un pointer, ~1 représente une barre oblique à l’intérieur d’un chemin : /paths/~1users/get correspond à GET /users.
Un champ vide est signalé comme tel, et un document qui n’est pas du JSON ou YAML valide est refusé en indiquant la ligne fautive : un collage cassé ne ressemble donc jamais à une comparaison propre.