API Contract Checker

Je plakt (of uploadt) een base (oude) en een revision (nieuwe) OpenAPI 3.x-specificatie, en de tool doorloopt elk path, parameter, request body, response, security requirement en schema in beide, en rapporteert vervolgens wat er is veranderd: toegevoegde of verwijderde endpoints, wijzigingen in verplichte parameters en requestvelden, versmalde types of enums, verdwenen responsevelden of statuscodes, wijzigingen in security requirements en wijzigingen in allOf/oneOf/anyOf-samenstelling.

Alles wat een bestaande client kan laten stoppen met werken: een verwijderd endpoint, een parameter of requestveld dat verplicht is geworden, een verwijderd responseveld of statuscode, een veld dat niet langer gegarandeerd wordt in een response, of een type/enum dat smaller is geworden (inclusief de nullable type-arrays van OpenAPI 3.1, bijvoorbeeld het verwijderen van "null" uit `["string", "null"]`). Nieuwe endpoints, nieuwe optionele velden en nieuwe responsevelden zijn additief en worden apart getoond als veilig.

Ja. Toegevoegde/verwijderde security requirements (globaal en per operatie), wijzigingen in security scheme-definities (bijvoorbeeld een API-key die verhuist van een header naar een queryparameter), nieuw gedepreceerde operaties en wijzigingen in server-URL's worden allemaal gerapporteerd - als informatieve bevindingen in plaats van breaking of safe, omdat (in lijn met de standaard ernst die oasdiff zelf aan deze checks toekent) geen van beide richtingen universeel goed of fout is; jij bepaalt of het relevant is voor jouw API.

Ja. `allOf`-leden worden opgelost en samengevoegd vóór het vergelijken, zodat een verplicht veld dat diep in een samengesteld schema is toegevoegd, nog steeds wordt opgemerkt. `oneOf`/`anyOf`-variantsets worden vergeleken en gemarkeerd als informatief wanneer een variant wordt toegevoegd of verwijderd, omdat of die specifieke wijziging breaking is afhangt van hoe jouw clients tussen varianten onderscheid maken.

Nee - dit vergelijkt alleen OpenAPI 3.x-specs. Swagger 2.0 (het oudere formaat) structureert parameters en bodies anders, dus dezelfde regels toepassen zou verkeerde resultaten geven. Het plakken van een Swagger 2.0-document geeft in plaats daarvan een duidelijke foutmelding, geen stilzwijgend onjuist diff.

Nee. Zowel het parsen als het vergelijken gebeurt in je browser - je spec verlaat nooit je apparaat, in tegenstelling tot de meeste andere OpenAPI diff-tools, die de upload op hun eigen server verwerken, zelfs als ze zeggen dat ze het niet opslaan. Dit geldt ook wanneer je de upload/drag-and-drop-optie gebruikt: het bestand wordt lokaal gelezen, nooit verzonden.

Het vergelijkt `application/json` request- en responsebodies, wat de grote meerderheid van REST-API's dekt, maar het beoordeelt geen andere content types, responseheaders, beschrijvingen of voorbeelden. Een `$ref` die buiten het document wijst (een apart bestand of URL) wordt gerapporteerd als onoplosbaar in plaats van stilzwijgend overgeslagen.

Ja, beide kan. Elk vak accepteert JSON of YAML onafhankelijk en detecteert welke je hebt gebruikt, zodat je een JSON-basisspec kunt vergelijken met een YAML-revisie of andersom. Je kunt ook een .json-/.yaml-/.yml-bestand op een van de vakken slepen, of de knop Upload file gebruiken - het bestand wordt in je browser gelezen en nooit ergens geüpload.

Het werkt met elk document met een "openapi": "3.x"-veld en een "paths"-object, wat zowel 3.0 als 3.1 dekt - inclusief de array-vorm van `type` in 3.1 (bijvoorbeeld `["string", "null"]`) - en wijst alleen documenten af die eruitzien als Swagger 2.0.

Text (.txt), Markdown (.md) en JSON (.json) worden allemaal ondersteund - kies er een uit het formaat-dropdown naast Download report voordat je downloadt. De JSON-export bevat de volledige lijst met bevindingen plus aantallen per ernst, zodat het naar een ander script (bijvoorbeeld een CI-check) kan worden doorgesluisd als je dat nodig hebt.

Beide werken: klik op Compare voor een directe herberekening, of blijf gewoon typen - na een korte pauze wordt het automatisch opnieuw vergeleken. Je kunt ook Ctrl+Enter (Cmd+Enter op Mac) indrukken vanuit een van beide vakken om direct te vergelijken zonder te wachten.