Comparateur OpenAPI
OpenAPI Diff
Compare deux documents OpenAPI et sépare les changements cassants des ajouts sans conséquence.
Compare deux versions d'un document OpenAPI et sépare les changements en cassants et additifs. La règle qu'il applique est écrite sur la page : un changement est cassant si une requête que l'ancien document acceptait peut désormais être rejetée, ou si une réponse qu'il promettait est une réponse qu'un client existant ne sait plus traiter.
Document précédent
Déposez la version précédente
Lu uniquement dans cet onglet.
Nouveau document
Déposez la nouvelle version
Lu uniquement dans cet onglet.
Cassants
8
Additifs
7
Verdict
Demande une version majeure
GET /pets
- cassantDésormais le paramètre `in: query` `limit` est obligatoire.
- ajoutéUn paramètre `in: query` `sort` facultatif a été ajouté.
- modifiéLe résumé ou la description a changé.
GET /pets · responses["200"].content["application/json"]
- cassant`[].id` a changé de type : de integer à string.
- cassantLa propriété `[].name` est désormais facultative.
- cassant`[].status` a gagné la valeur d’enum "pending".
- ajoutéUne propriété facultative `[].owner` a été ajoutée.
GET /pets/{petId} · responses["200"].content["application/json"]
- cassant`id` a changé de type : de integer à string.
- cassantLa propriété `name` est désormais facultative.
- cassant`status` a gagné la valeur d’enum "pending".
- ajoutéUne propriété facultative `owner` a été ajoutée.
GET /pets/{petId}
- cassantLa réponse `404` a disparu.
DELETE /pets/{petId}
- ajoutéL’opération a été ajoutée.
components.schemas.Owner
- ajoutéLe schéma a été ajouté.
info.version
- modifié`1.0.0` → `2.0.0`
Ce qui compte comme cassant
En une phrase : une requête que le document précédent acceptait risque d’être rejetée, ou une réponse qu’il promettait est une réponse qu’un client existant ne sait plus traiter. Donc : retirer un chemin, une opération, un code de réponse, un type de média ou une propriété de réponse ; ajouter un paramètre obligatoire ou une propriété de requête obligatoire ; un passage de facultatif à obligatoire ; un changement de type ; retirer une valeur d’un enum de requête ; ajouter une valeur à un enum de réponse (le switch du client n’a pas de case pour elle) ; et une propriété de réponse qui passe d’obligatoire à facultative. Les directions inverses, ainsi que les changements de descriptions, de balises, d’operationId et de marques deprecated, sont compatibles.
- · Les schémas sont comparés après avoir suivi les
$refinternes au document, si bien que renommer un composant n’est pas un changement. Les paramètres de chemin sont appariés par position et non par nom. - · L’intérieur de
oneOf·anyOf·notest comparé d’un bloc et signalé comme cassant s’il diffère — aucun raisonnement n’est fait dessus. - · Un
$refqui pointe vers un autre fichier n’est pas suivi. Regroupez d’abord les fichiers en un seul.
Pour vérifier un seul document, utilisez Vérification OpenAPI.
Comment s’en servir
Mettez l'ancien et le nouveau document côte à côte
JSON ou YAML pour l'un comme pour l'autre. Les deux sont analysés dans cet onglet : une spécification non publiée ne quitte donc pas votre machine.
Lisez le verdict
Nombre de changements cassants, nombre d'additifs, et ce que cela veut dire pour le numéro de version : une majeure, une mineure, ou rien du tout parce que le contrat est inchangé.
Filtrez sur les cassants et lisez-les
Groupés par opération, chacun avec ce qui a changé. La copie Markdown est mise en forme pour une description de pull request.
Questions fréquentes
Pourquoi ajouter une valeur d'énumération à une réponse est-il cassant ?
Parce qu'un client existant a un aiguillage sans cas pour elle. Ajouter à une énumération de *requête* est sans danger — le serveur accepte plus qu'avant ; ajouter à une énumération de réponse envoie aux clients quelque chose dont on ne leur avait jamais parlé. C'est le sens qui décide.
J'ai renommé un composant et il ne signale aucun changement.
C'est correct. Les schémas sont comparés après résolution des `$ref` : un composant renommé de même forme est le même contrat. Les noms dans `components` sont internes ; les clients voient la forme résolue.
Une propriété de réponse obligatoire qui devient facultative est-elle vraiment cassante ?
Oui, du côté du client. On lui avait promis que le champ serait toujours là et son code le lit sans condition ; le rendre facultatif signifie que le serveur peut désormais l'omettre. Obligatoire et facultatif échangent de sens entre la requête et la réponse, et c'est la partie que l'on prend à l'envers.
Comment traite-t-il `oneOf` et `anyOf` ?
Ils sont comparés en bloc et signalés comme cassants s'ils diffèrent le moins du monde. Déterminer si une union est un sur-ensemble d'une autre est une procédure de décision que ceci n'essaie délibérément pas ; un faux « cassant » que vous pouvez écarter vaut mieux qu'un faux « sans danger » que vous ne pouvez pas.
À alimenter depuis
Comparateur JSON
JSON Diff
Compare deux documents JSON sur leur structure, sans tenir compte de l’ordre des clés, et signale les chemins ajoutés, retirés et modifiés.
Analyseur OpenAPI
OpenAPI Linter
Contrôle un document OpenAPI et signale les réponses manquantes, les schémas inutilisés, les références qui ne pointent sur rien et les autres défauts qui cassent les générateurs de code.
Testeur de plage semver
Semver Range Tester
Indique quelles versions satisfont une plage, compare deux versions et trie une liste dans l’ordre de préséance.
Formateur et validateur JSON
JSON Formatter & Validator
Met en forme, minifie et valide du JSON en désignant la ligne et la colonne exactes de l’erreur de syntaxe.
Ensuite
Ces outils acceptent ce que celui-ci produit : le résultat peut y aller directement.
Comparateur JSON
JSON Diff
Compare deux documents JSON sur leur structure, sans tenir compte de l’ordre des clés, et signale les chemins ajoutés, retirés et modifiés.
Validateur JSON Schema
JSON Schema Validator
Valide un document contre un JSON Schema et rapporte chaque échec avec le chemin exact dans l’instance.
Analyseur OpenAPI
OpenAPI Linter
Contrôle un document OpenAPI et signale les réponses manquantes, les schémas inutilisés, les références qui ne pointent sur rien et les autres défauts qui cassent les générateurs de code.
Testeur de plage semver
Semver Range Tester
Indique quelles versions satisfont une plage, compare deux versions et trie une liste dans l’ordre de préséance.
Conversion JSON ⇄ CSV
JSON ⇄ CSV
Aplatit du JSON imbriqué en colonnes ou reconstruit des objets depuis un tableau, avec un nommage des colonnes par chemin pointé.
Formateur et validateur JSON
JSON Formatter & Validator
Met en forme, minifie et valide du JSON en désignant la ligne et la colonne exactes de l’erreur de syntaxe.