OpenAPI Diff

Ce que ce comparateur vérifie — et ce que « incompatible » signifie vraiment

Un changement est incompatible quand un client écrit correctement contre l’ancienne spécification peut échouer contre la nouvelle sans changer une ligne de son propre code. Cette définition guide chaque verdict de cette page. Supprimer un chemin ou une opération est incompatible parce que les appels existants n’ont nulle part où aller. Supprimer un statut de réponse — surtout un 2xx — est incompatible parce que la gestion d’erreurs du client a été écrite autour de l’ancien ensemble. Ajouter un paramètre obligatoire ou une propriété de requête obligatoire est incompatible parce que la requête valide d’hier est soudain rejetée. Changer le type ou le format d’un champ est incompatible parce que les analyseurs, validateurs et SDK générés reposent tous sur le type déclaré. Retirer une valeur d’énumération est incompatible parce qu’un client peut encore l’envoyer, ou conserver des données qu’il ne peut plus interpréter. Tout le reste — un nouveau point de terminaison, un paramètre facultatif, un nouveau champ de réponse, une nouvelle valeur d’énumération, un nouveau code de statut — est signalé comme compatible : les anciens clients continuent de fonctionner, même s’ils ne peuvent pas encore utiliser la nouvelle capacité.

La comparaison est structurelle, pas textuelle. Les deux documents sont normalisés dans le même modèle avant toute comparaison : chaque chemin et chaque opération, leurs paramètres indexés par nom et emplacement, leur corps de requête et chaque réponse réduits à une signature de schéma — un résumé déterministe des types, formats, noms de propriétés, listes de champs obligatoires et valeurs d’énumération, construit récursivement et avec les références locales $ref résolues. C’est pourquoi réordonner les clés, reformater les espaces ou réécrire chaque description produit un diff vide : rien de tout cela ne change le contrat. Et c’est pourquoi un changement enfoui à trois niveaux dans un schéma référencé est quand même trouvé — la signature développe la référence au lieu de comparer son nom.

Deux formes d’entrée sont acceptées parce que l’écosystème publie les deux : le JSON est essayé d’abord et, quand cela échoue, le texte est analysé comme YAML, le format qu’utilisent la plupart des documents OpenAPI écrits à la main. Les documents Swagger 2.0 fonctionnent aussi, y compris leurs paramètres in: body et leurs schémas par réponse. Il n’y a délibérément ni récupération distante ni téléversement : collez les documents ou déposez les fichiers, exactement comme vous le feriez avec une capture HAR, et la comparaison s’exécute quand vous appuyez sur le bouton — pas à chaque frappe —, de sorte que deux grandes spécifications collées restent réactives.

Utilisez le résultat comme une porte de publication, pas comme une décoration. Dans une revue, la liste des incompatibles est l’ordre du jour : chaque entrée a besoin d’un correctif, d’une montée de version, d’une fenêtre d’obsolescence ou d’une décision écrite que la rupture est voulue et communiquée. La liste des compatibles est le brouillon du journal des changements. Exporter le diff en JSON permet d’archiver cette décision à côté de la version, et le résumé copiable entre directement dans une demande de tirage — la même discipline que vous appliqueriez à un changement de contrat de webhook, où une charge utile modifiée en silence casse tous les abonnés d’un coup.

Limites honnêtes, dites clairement. Ce comparateur compare le contrat déclaré : il ne peut pas voir le comportement que la spécification ne déclare pas, comme un champ qui garde son type mais change de sens, une nouvelle règle métier, des limites de débit plus strictes ou un message d’erreur que les clients analysaient (imprudemment). Il suit les références locales et compare les schémas jusqu’à une profondeur bornée, de sorte que les schémas pathologiquement imbriqués ou mutuellement récursifs sont résumés plutôt que développés à l’infini. Et un diff avec zéro changement incompatible n’est pas une promesse qu’une mise à niveau est sûre — c’est la preuve que le contrat documenté a tenu, ce qui est exactement la preuve qu’il vaut la peine d’avoir avant de déployer.