Verificator de contract API

Lipești (sau încarci) o specificație de bază (veche) și una revizuită (nouă) OpenAPI 3.x, iar instrumentul parcurge fiecare cale, parametru, request body, response, cerință de security și schemă din ambele, apoi raportează ce s-a schimbat: endpointuri adăugate sau eliminate, schimbări ale obligativității parametrilor și câmpurilor din request, tipuri sau enum-uri restrânse, câmpuri de response sau coduri de status dispărute, schimbări ale cerințelor de security și schimbări de compoziție allOf/oneOf/anyOf.

Orice ar putea opri funcționarea unui client existent: un endpoint eliminat, un parametru sau câmp din request care a devenit obligatoriu, un câmp de response sau cod de status eliminat, un câmp care nu mai este garantat într-un response, sau un tip/enum devenit mai restrâns (inclusiv array-urile de tip nullable din OpenAPI 3.1, de exemplu eliminarea "null" din `["string", "null"]`). Endpointurile noi, câmpurile opționale noi și câmpurile noi de response sunt aditive și sunt afișate separat, ca fiind sigure.

Da. Cerințele de security adăugate/eliminate (globale și per operație), schimbările definiției schemei de security (de exemplu, o cheie API mutată dintr-un header într-un parametru de query), operațiile marcate recent ca deprecated și schimbările URL-ului serverului sunt toate raportate - ca informații, nu ca fiind incompatibile sau sigure, deoarece (în conformitate cu severitatea implicită pe care oasdiff însuși o atribuie acestor verificări) nicio direcție nu este universal corectă sau greșită; tu decizi dacă contează pentru API-ul tău.

Da. Membrii `allOf` sunt rezolvați și combinați înainte de comparare, astfel încât un câmp obligatoriu adăugat în profunzime într-o schemă compusă este tot detectat. Seturile de variante `oneOf`/`anyOf` sunt comparate și marcate ca informative atunci când o variantă este adăugată sau eliminată, deoarece dacă acea schimbare specifică este incompatibilă depinde de modul în care clienții tăi disting între variante.

Nu - acest instrument compară exclusiv specificații OpenAPI 3.x. Swagger 2.0 (formatul mai vechi) structurează parametrii și body-urile diferit, așa că aplicarea acelorași reguli ar produce rezultate greșite. Lipirea unui document Swagger 2.0 produce o eroare clară, în loc de un diff greșit în tăcere.

Nu. Atât parsarea, cât și compararea rulează în browserul tău - specificația nu părăsește niciodată dispozitivul tău, spre deosebire de majoritatea celorlalte instrumente de diff pentru OpenAPI, care procesează fișierul încărcat pe propriul server chiar și atunci când susțin că nu îl stochează. Acest lucru este valabil și când folosești opțiunea de încărcare a fișierului prin drag-and-drop: fișierul este citit local și nu este niciodată transmis.

Compară corpurile de request și response de tip `application/json`, ceea ce acoperă marea majoritate a API-urilor REST, dar nu evaluează alte tipuri de conținut, headere de response, descrieri sau exemple. Un `$ref` care indică în afara documentului (un fișier separat sau un URL) este raportat ca nerezolvabil, în loc să fie ignorat în tăcere.

Da, ambele. Fiecare casetă acceptă independent JSON sau YAML și detectează ce ai folosit, așa că poți compara o specificație de bază în JSON cu o revizie în YAML sau invers. Poți de asemenea să tragi un fișier .json/.yaml/.yml peste oricare dintre casete, sau să folosești butonul Upload file - fișierul este citit în browser și nu este niciodată încărcat nicăieri.

Funcționează cu orice document care are un câmp "openapi": "3.x" și un obiect "paths", ceea ce acoperă atât 3.0, cât și 3.1 - inclusiv forma de tip array a `type` din 3.1 (de exemplu `["string", "null"]`) - și respinge doar documentele care par a fi Swagger 2.0.

Sunt suportate Text (.txt), Markdown (.md) și JSON (.json) - alege unul din lista derulantă de format de lângă Download report înainte de a descărca. Exportul JSON include lista completă a constatărilor, plus numărul pe fiecare nivel de severitate, deci poate fi trimis către un alt script (de exemplu, o verificare CI) dacă ai nevoie de asta.

Funcționează în ambele moduri: apasă Compare pentru o re-rulare instantanee, sau pur și simplu continuă să scrii - după o scurtă pauză, comparația se reia automat. De asemenea, poți apăsa Ctrl+Enter (Cmd+Enter pe Mac) din oricare dintre casete pentru a compara imediat, fără să aștepți.