Le travail à faire
Détectez le changement de contrat avant qu’un client ne le fasse.
Un fichier OpenAPI peut changer dans une demande d’extraction sans que personne ne remarque qu’un champ de réponse a disparu, qu’un paramètre de requête est devenu obligatoire ou qu’une énumération a perdu une valeur. Dans une longue spécification, des modifications comme celles-ci se cachent parmi les modifications de formatage et les nouveaux points de terminaison.
Diff Anything compare la spécification publiée et le candidat en tant que documents analysés en mode schéma API et étiquette les modifications qui correspondent à ses règles de modification avec rupture avec un code de règle. Les étiquettes vous donnent une courte liste à lire en premier ; décider si les clients sont concernés reste votre décision.
Chemin recommandé
De la spécification publiée à une liste révisée de modifications.
Utilisez la spécification dont dépendent les clients aujourd’hui comme côté gauche et la version proposée comme côté droit.
Ouvrir les deux spécifications
Choisissez les fichiers de schéma OpenAPI, Swagger ou JSON écrits en JSON ou YAML. Les reconnaît automatiquement à partir de leur clé openapi, swagger ou $schema de niveau supérieur et ouvre le mode schéma API.
Lire le verdict
Une note au-dessus du résultat donne le nombre de modifications potentiellement graves ou indique que les schémas sont équivalents. Lorsqu’aucune règle ne correspond, cela vous rappelle qu’une révision manuelle du contrat est toujours requise.
Filtre à rupture
Choisissez Rupture dans le filtre du volet Différences. Chaque entrée affiche son code de règle, tel que API001 pour une opération supprimée ou API004 pour une nouvelle entrée requise, ainsi que le chemin de la modification.
Lisez ce que les règles laissent sans étiquette
Revenez à Tout. Un modèle modifié ou un paramètre renommé apparaît sans code de règle, et l’insertion d’un paramètre peut décaler les positions de ceux qui le suivent.
Gatez la construction
Avec Pro, dans la version du Microsoft Store sous Windows ou via l’outil en ligne de commande gratuit sur Mac, exécutez --mode api --fail-on breaking, ou définissez failOn: breaking pour la paire dans un manifeste de lot qui écrit du JUnit ou du SARIF. Les schémas identiques passent, et la tâche échoue uniquement en cas de modifications incompatibles ou non classées.
Capacités impliquées
Comment les trois capacités s’intègrent dans une revue API.
Limites à connaître
Lisez les étiquettes comme point de départ.
Les règles jugent un changement par sa localisation dans le document. Ils ne résolvent pas $ref et ne traitent pas les schémas de demande et de réponse de la même manière, donc certains éléments signalés sont inoffensifs et certaines modifications incompatibles, comme un paramètre renommé, une entrée de composants supprimée ou l’ajout de AdditionalProperties : false, ne comportent aucun code de règle.
Une vérification réussie avec --fail-on breaking signifie qu’aucune règle n’a été déclenchée. Elle ne prouve pas que les clients ne sont pas affectés. Faites examiner par une personne les changements que les règles ne peuvent pas évaluer.
Les règles sémantiques telles que Ignorer les chemins ne s’appliquent pas en mode schéma API. Free affiche les résultats complets d’API dans l’application dans les limites de 5 Mo et de 10 par jour ; le mode ligne de commande de l’API et les manifestes par lots nécessitent Pro.
Manuel associé
Utiliser Diff Anything en ligne de commande, avec Git et en CI
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.
Ses sections couvrent la recherche de l’exécutable installé, l’entrée en mode cli explicite, l’interprétation des codes de sortie, le choix de la sortie pour le consommateur, la configuration de git difftool, l’utilisation de diff pour git diff, la fusion avec git, l’exécution de manifestes par lots, le débogage des échecs d’automatisation. Utilisez-le lorsque vous êtes prêt à reproduire ce flux de travail avec vos propres données de projet.
Lire le guideRéponses directes
Questions sur ce cas d’utilisation.
Quels formats de description d’API puis-je comparer ?
Documents de schéma OpenAPI 3, Swagger 2.0 et JSON dans JSON ou YAML. Le mode schéma API accepte également les types GraphQL et les instructions SQL CREATE TABLE, avec un ensemble de vérifications plus restreint.
Une modification signalée interrompt-elle toujours les clients ?
Non. Un indicateur signifie que la modification correspond à une règle, par exemple API008, lorsque des exigences de sécurité sont ajoutées ou modifiées. Lisez l’emplacement et décidez si les demandes ou réponses existantes sont affectées.
Puis-je utiliser la ligne de commande comme porte de libération ?
Oui, avec Pro, sous Windows ou, via l’outil en ligne de commande gratuit, sur Mac. --mode api --fail-on breaking, ou failOn: breaking dans un manifeste de lot, laisse passer les schémas identiques et les modifications compatibles et échoue en cas de modifications incompatibles ou non classées. Comme les règles sont heuristiques, considérez cette vérification comme un premier filtre et examinez toujours les modifications du contrat.
Puis-je exécuter des comparaisons d’API sur un Mac ?
Oui, dans l’application sous macOS et Windows. Sur Mac, l’exécution en ligne de commande, la configuration de git difftool et l’utilisation en CI passent par l’outil en ligne de commande gratuit, qui ajoute la commande diff-anything à la version du Mac App Store ; la version du Microsoft Store sous Windows inclut la ligne de commande.
Gratuit & 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.