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 Microsoft Store sur Windows, exécutez --mode api --fail-on breaking ou définissez failOn : Break pour la paire dans un manifeste par lots qui écrit JUnit ou SARIF. Les schémas identiques réussissent et le travail échoue uniquement en cas de modifications incompatibles ou non classifié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 sur Windows. --mode api --fail-on breaking, ou failOn : rupture dans un manifeste par lots, transmet les schémas identiques et les modifications incassables et échoue en cas de rupture ou de modifications non classifiées. Parce que les règles sont heuristiques, traitez-les comme une première porte tout en examinant les modifications du contrat.
Puis-je exécuter des comparaisons d’API sur un Mac ?
Oui, dans l’application sur macOS et Windows. Les exécutions de la ligne Command, la configuration du difftool Git et l’utilisation de CI sont disponibles avec la version Microsoft Store sur Windows.
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 premiers octets de différences et les aperçus PDF des 3 premières pages. La comparaison du texte brut, des notebooks JSON et Jupyter est complète et l’ouverture de fichiers à partir du Finder ou de l’Explorateur de fichiers, des liens diffanything:// et AppleScript est gratuite. La CLI gratuite prend en charge le texte, JSON et les notebooks. 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 correctifs JSON, 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 par lots, les préprocesseurs de confiance et chaque mode CLI.