Réponse directe
Diff Anything peut-il détecter les changements incompatibles OpenAPI ?
Diff Anything compare OpenAPI et JSON Schema en tant que contrats analysés et étiquette les modifications incompatibles probables avec des codes de règle heuristiques, comme une opération supprimée ou une nouvelle entrée obligatoire. Avec Pro, la CLI et les manifestes de lot exécutent la même comparaison en CI, avec la version du Microsoft Store sous Windows ou l’outil en ligne de commande gratuit pour la version du Mac App Store : les schémas identiques passent, et --fail-on breaking fait échouer la tâche uniquement en cas de modifications incompatibles ou non classées, avec le code de règle de chaque résultat dans JUnit et SARIF. Les règles sont heuristiques : les résultats signalés comme ceux qui passent nécessitent donc toujours une revue du contrat.
Schémas pris en charge
Schéma OpenAPI, JSON, GraphQL et tables SQL.
Le mode Schéma API compare les documents de schéma OpenAPI et JSON écrits en JSON ou YAML. Les détecte automatiquement à partir des clés de niveau supérieur telles que openapi, swagger ou $schema. Le même mode lit également le type GraphQL, les définitions d’interface et d’entrée, ainsi que les instructions SQL CREATE TABLE.
Chaque modification est répertoriée avec son emplacement, par exemple $.paths["/users"].get.parameters[0]. Si les deux côtés sont écrits dans des langages de schéma différents, le résultat indique que la classification est uniquement structurelle.
Règles de rupture-changement
Les modifications incompatibles probables sont étiquetées avec un code de règle.
Chaque différence est vérifiée par rapport à un ensemble de règles de compatibilité. Une correspondance est étiquetée « Modification de rupture API » avec son code de règle, et le filtre de rupture dans la liste des différences affiche uniquement ces éléments. Une note au-dessus du résultat donne le verdict, tel que « 2 changements API potentiellement cassants détectés par les règles heuristiques ». Les schémas identiques ou équivalents, y compris le même schéma écrit une fois dans JSON et une fois dans YAML, ne signalent aucune différence.
- API001 : une opération, un paramètre, une réponse ou un chemin a été supprimé
- API002 : un membre de champ, de colonne ou de type a été supprimé
- API003 : une valeur a été supprimée d’une énumération, oneOf ou anyOf
- API004 : une nouvelle entrée obligatoire a été ajoutée
- API005 : une valeur facultative ou nullable est devenue obligatoire
- API006 et API007 : une contrainte minimale ou maximale devenue plus stricte
- API008 : des exigences de sécurité ont été ajoutées ou modifiées
- API009 : le type, le format ou $ref d’un schéma a été modifié, ou une valeur dans ses propriétés a changé de type
- API010 : une signature de champ GraphQL ou une définition de colonne SQL modifiée
Comment le lire
Traitez le classement comme une aide à la révision.
Les règles déterminent où se situe une modification dans le document. Ils ne distinguent pas les schémas de requête des schémas de réponse, donc une nouvelle propriété de réponse obligatoire est marquée de la même manière qu’un nouveau champ de requête obligatoire. Les références ($ref) sont comparées telles qu’écrites et non résolues : une référence modifiée est signalée sous API009, mais le schéma vers lequel elle pointe n’est pas comparé. Les modifications apportées aux mots-clés tels que le modèle sont répertoriées sans code de règle. La suppression d’une entrée entière sous composants, le renommage ou le déplacement d’un paramètre, l’ajout de propriétés supplémentaires : false et la suppression des exigences de sécurité ne sont pas classés comme des ruptures.
Les tableaux tels que les paramètres sont comparés par position, donc l’insertion d’un paramètre peut également afficher les modifications aux positions ultérieures. Lisez chaque élément signalé avant de décider si les clients sont concernés. Le résultat est le même : lorsqu’aucune règle ne correspond, une révision manuelle du contrat est toujours requise.
Portail CI
Échec d’une tâche CI uniquement en cas de modifications incompatibles avec Pro.
Avec Pro, --mode api exécute la comparaison en ligne de commande avec une sortie summary, terminal ou JSON, sous Windows et, via l’outil en ligne de commande gratuit, sur Mac. Ajoutez --fail-on breaking et la commande renvoie 1 uniquement lorsqu’une modification est incompatible ou n’a pas pu être classée ; les schémas identiques et les modifications compatibles renvoient 0.
Dans un manifeste de lot, définissez failOn : Breaking sur un cas API. La sortie JUnit répertorie les modifications incompatibles avec leurs codes de règle, et SARIF rapporte chaque résultat comme son propre résultat, avec les modifications incompatibles sous leur code de règle comme erreurs. Les règles sont heuristiques, alors considérez la réussite du contrôle comme une première porte, et non comme une preuve que les clients ne sont pas affectés.
Idéal pour
Où s’inscrit ce flux de travail.
- Examen d’une modification de schéma OpenAPI ou JSON avant sa diffusion auprès des clients
- Obtenir une première liste des changements probables à vérifier manuellement
- Comparaison des définitions API qui doivent rester sur votre propre machine
Aucun compte, service de comparaison cloud, analyse ou télémétrie.
Capacités pertinentes
Ce que Diff Anything apporte au travail.
Flux de travail pratique
De la configuration à un résultat révisé.
Ouvrir les spécifications publiées et candidates
Choisissez les deux fichiers de schéma OpenAPI ou JSON. Les ouvre automatiquement en mode schéma API.
Filtre à rupture
Utilisez le filtre Breaking pour voir en premier les modifications qui correspondent à une règle de compatibilité.
Vérifiez chaque changement signalé
Lisez le code et l’emplacement de la règle, puis décidez si cela affecte les demandes, les réponses ou ni l’un ni l’autre.
Vérifier les modifications restantes
Revenez à Tous pour vérifier les modifications que les règles ne classent pas, telles que les modifications de modèle ou un paramètre renommé.
Utile en pratique
Réponses directes
Questions sur l’outil de comparaison OpenAPI.
Diff Anything peut-il détecter les modifications importantes d’OpenAPI ?
Diff Anything compare OpenAPI et JSON Schema en tant que contrats analysés et étiquette les modifications incompatibles probables avec des codes de règle heuristiques, comme une opération supprimée ou une nouvelle entrée obligatoire. Avec Pro, la CLI et les manifestes de lot exécutent la même comparaison en CI, avec la version du Microsoft Store sous Windows ou l’outil en ligne de commande gratuit pour la version du Mac App Store : les schémas identiques passent, et --fail-on breaking fait échouer la tâche uniquement en cas de modifications incompatibles ou non classées, avec le code de règle de chaque résultat dans JUnit et SARIF. Les règles sont heuristiques : les résultats signalés comme ceux qui passent nécessitent donc toujours une revue du contrat.
Est-il compatible avec Swagger 2.0 et OpenAPI 3 ?
Les deux sont détectés et comparés en tant que documents JSON ou YAML. Les mêmes règles de compatibilité s’appliquent aux deux ; il n’y a pas de règles spécifiques à la version.
Les références $ref sont-elles résolues ?
Non. Les références sont comparées telles qu’elles sont écrites, donc une $ref modifiée est signalée sous API009, mais le schéma vers lequel elle pointe n’est pas comparé. Les fichiers de référence externes ne sont pas chargés.
Une tâche CI peut-elle échouer uniquement en cas de modifications incompatibles ?
Oui, avec Pro, sous Windows ou, via l’outil en ligne de commande gratuit, sur Mac. Utilisez --mode api --fail-on breaking, ou failOn: breaking dans un manifeste de lot. La tâche échoue uniquement en cas de modifications incompatibles ou non classées, et les schémas identiques passent.
La comparaison des schémas d’API fait-elle partie du forfait gratuit ?
Dans l’application, oui : le forfait gratuit affiche le résultat complet pour les fichiers jusqu’à 5 Mo, avec 10 comparaisons par jour. Le mode API de ligne de commande, --fail-on breaking et les manifestes par lots nécessitent Pro.
Aller plus loin
Sous Windows, lancer des comparaisons reproductibles, comprendre les codes de sortie, intégrer Git et produire des résultats lisibles par une machine pour la CI.
Lire Utiliser Diff Anything depuis la CLI, Git et CIGratuit & Pro : ce qui est inclus
Disponible sur le Mac App Store et le Microsoft Store. L’utilisation de la version gratuite de l’app vous permet d’essayer tous les moteurs de comparaison pour des fichiers jusqu’à 5 Mo par côté et 10 nouvelles sessions de comparaison par jour local ; les aperçus de collection affichent les 100 premiers éléments, les comparaisons binaires les 100 premières différences d’octets et les aperçus PDF les 3 premières pages. La comparaison du texte brut, du JSON et des notebooks Jupyter est complète, et l’ouverture de fichiers à partir du Finder ou de l’Explorateur de fichiers, les liens diffanything:// et AppleScript sont gratuits. La CLI gratuite prend en charge le texte, le JSON et les notebooks, et l’outil en ligne de commande qui apporte la CLI à la version du Mac App Store se télécharge gratuitement et utilise l’achat Pro effectué dans l’app. Un achat Pro unique supprime les limites d’aperçu et de session et déverrouille des sources plus volumineuses dans les limites techniques, les profils et l’historique enregistrés, l’enregistrement des instantanés de dossiers, l’exportation et l’impression de rapports, l’exportation de JSON Patch, l’application de correctifs, la fusion à trois voies et la résolution des conflits, le pilote de fusion et l’outil de fusion Git, la synchronisation des dossiers, les manifestes de lot, tous les modes CLI et, sous Windows, les préprocesseurs de confiance.