Vérificateur de Contrats API

Vous collez (ou importez) une spec OpenAPI 3.x de base (ancienne) et une de révision (nouvelle), et l'outil parcourt chaque chemin, paramètre, corps de requête, réponse, exigence de sécurité et schéma des deux, puis indique ce qui a changé : endpoints ajoutés ou supprimés, changements dans les exigences des paramètres et des champs de requête, types ou enums restreints, champs de réponse ou codes de statut disparus, changements des exigences de sécurité et changements de composition allOf/oneOf/anyOf.

Tout ce qui pourrait empêcher un client existant de fonctionner : un endpoint supprimé, un paramètre ou champ de requête devenu obligatoire, un champ de réponse ou un code de statut supprimé, un champ qui n'est plus garanti dans une réponse, ou un type/enum devenu plus restrictif (y compris les tableaux de type nullable d'OpenAPI 3.1, par exemple retirer "null" de `["string", "null"]`). Les nouveaux endpoints, les nouveaux champs optionnels et les nouveaux champs de réponse sont additifs et affichés séparément comme sûrs.

Oui. Les exigences de sécurité ajoutées ou supprimées (globales et par opération), les changements de définition du schéma de sécurité (par exemple une clé d'API qui passe d'un en-tête à un paramètre de requête), les opérations nouvellement dépréciées et les changements d'URL de serveur sont tous signalés - comme des constats informatifs plutôt que cassants ou sûrs, car (conformément à la sévérité par défaut qu'oasdiff attribue lui-même à ces vérifications) aucune direction n'est universellement bonne ou mauvaise ; c'est à vous de décider si cela compte pour votre API.

Oui. Les membres d'`allOf` sont résolus et fusionnés avant la comparaison, donc un champ obligatoire ajouté au fond d'un schéma composé est tout de même détecté. Les ensembles de variantes `oneOf`/`anyOf` sont comparés et signalés comme informatifs lorsqu'une variante est ajoutée ou supprimée, car le caractère cassant ou non de ce changement précis dépend de la façon dont vos clients distinguent les variantes.

Non - cet outil compare uniquement des specs OpenAPI 3.x. Swagger 2.0 (l'ancien format) structure différemment les paramètres et les corps de requête, donc appliquer les mêmes règles donnerait des résultats erronés. Coller un document Swagger 2.0 produit une erreur claire plutôt qu'un diff silencieusement faux.

Non. L'analyse et la comparaison s'exécutent toutes deux dans votre navigateur - votre spec ne quitte jamais votre appareil, contrairement à la plupart des autres outils de diff OpenAPI, qui traitent le fichier importé sur leur propre serveur même quand ils affirment ne pas le stocker. Cela reste vrai avec l'option d'import de fichier par glisser-déposer : le fichier est lu localement, jamais transmis.

Il compare les corps de requête et de réponse `application/json`, ce qui couvre la grande majorité des API REST, mais il n'évalue pas les autres types de contenu, les en-têtes de réponse, les descriptions ou les exemples. Un `$ref` qui pointe en dehors du document (un fichier ou une URL séparés) est signalé comme non résolu plutôt que silencieusement ignoré.

Oui, les deux. Chaque zone accepte le JSON ou le YAML indépendamment et détecte celui que vous avez utilisé, vous pouvez donc comparer une spec de base en JSON à une révision en YAML ou l'inverse. Vous pouvez aussi glisser un fichier .json/.yaml/.yml sur l'une des zones, ou utiliser son bouton Upload file - le fichier est lu dans votre navigateur et jamais envoyé nulle part.

Il fonctionne avec tout document possédant un champ "openapi": "3.x" et un objet "paths", ce qui couvre 3.0 et 3.1 - y compris le `type` sous forme de tableau de 3.1 (par exemple `["string", "null"]`) - et ne rejette que les documents qui ressemblent à du Swagger 2.0.

Text (.txt), Markdown (.md) et JSON (.json) sont tous pris en charge - choisissez-en un dans le menu déroulant de format à côté de Download report avant de télécharger. L'export JSON inclut la liste complète des constats ainsi que les compteurs par sévérité, il peut donc être transmis à un autre script (par exemple une vérification CI) si besoin.

Les deux fonctionnent : cliquez sur Compare pour relancer instantanément, ou continuez simplement à taper - après une brève pause, la comparaison se relance automatiquement. Vous pouvez aussi appuyer sur Ctrl+Enter (Cmd+Enter sur Mac) depuis l'une ou l'autre zone pour comparer immédiatement sans attendre.