API Contract Checker

Sie fügen eine base (alte) und eine revision (neue) OpenAPI-3.x-Spezifikation ein (oder laden sie hoch), und das Tool durchläuft jeden path, parameter, request body, response, security requirement und schema in beiden, und meldet dann, was sich geändert hat: hinzugefügte oder entfernte Endpunkte, Änderungen bei parameter- und request-field-Pflichtangaben, eingeengte Typen oder Enums, verschwundene response-Felder oder Statuscodes, Änderungen bei security requirements und allOf/oneOf/anyOf-Kompositionsänderungen.

Alles, was einen bestehenden Client zum Ausfall bringen könnte: ein entfernter Endpunkt, ein parameter oder request field, das required wurde, ein entferntes response-Feld oder ein entfernter Statuscode, ein Feld, das in einer Response nicht mehr garantiert ist, oder ein Typ/Enum, das enger wurde (einschließlich OpenAPI-3.1-nullable-type-Arrays, z. B. das Entfernen von "null" aus `["string", "null"]`). Neue Endpunkte, neue optionale Felder und neue response-Felder sind additiv und werden separat als safe angezeigt.

Ja. Hinzugefügte/entfernte security requirements (global und pro Operation), Änderungen an security-scheme-Definitionen (z. B. ein API-Key, der von einem Header zu einem Query-Parameter wechselt), neu als deprecated markierte Operationen und Server-URL-Änderungen werden alle gemeldet - als informational findings statt breaking oder safe, denn (passend zur Standard-Severity, die oasdiff selbst diesen Prüfungen zuweist) ist keine Richtung universell richtig oder falsch; Sie entscheiden, ob es für Ihre API relevant ist.

Ja. `allOf`-Mitglieder werden vor dem Diffing aufgelöst und zusammengeführt, sodass ein tief in einem zusammengesetzten Schema hinzugefügtes required Feld trotzdem erkannt wird. `oneOf`/`anyOf`-Variantensets werden verglichen und als informational markiert, wenn eine Variante hinzugefügt oder entfernt wird, da es von der Art abhängt, wie Ihre Clients zwischen Varianten unterscheiden, ob diese konkrete Änderung breaking ist.

Nein - es vergleicht nur OpenAPI-3.x-Specs. Swagger 2.0 (das ältere Format) strukturiert parameter und bodies anders, sodass dieselben Regeln falsche Ergebnisse liefern würden. Das Einfügen eines Swagger-2.0-Dokuments erzeugt stattdessen eine klare Fehlermeldung statt eines stillschweigend falschen Diffs.

Nein. Parsing und Vergleich laufen beide in Ihrem Browser - Ihre Spec verlässt nie Ihr Gerät, anders als bei den meisten anderen OpenAPI-Diff-Tools, die den Upload auf ihrem eigenen Server verarbeiten, selbst wenn sie behaupten, ihn nicht zu speichern. Das gilt auch bei Nutzung der Datei-Upload/Drag-and-Drop-Option: Die Datei wird lokal gelesen, nie übertragen.

Es vergleicht `application/json`-Request- und Response-Bodies, was den Großteil der REST-APIs abdeckt, bewertet aber keine anderen Content-Types, Response-Header, Beschreibungen oder Beispiele. Ein `$ref`, der außerhalb des Dokuments verweist (eine separate Datei oder URL), wird als unresolvable gemeldet statt stillschweigend übersprungen.

Beides ist möglich. Jedes Feld akzeptiert JSON oder YAML unabhängig voneinander und erkennt, welches Format verwendet wurde, sodass Sie eine JSON-base-Spec mit einer YAML-revision vergleichen können oder umgekehrt. Sie können auch eine .json/.yaml/.yml-Datei auf eines der Felder ziehen oder den Upload file-Button nutzen - die Datei wird in Ihrem Browser gelesen und nie irgendwohin hochgeladen.

Es funktioniert mit jedem Dokument, das ein "openapi": "3.x"-Feld und ein "paths"-Objekt hat, was sowohl 3.0 als auch 3.1 abdeckt - einschließlich des array-form `type` von 3.1 (z. B. `["string", "null"]`) - und lehnt nur Dokumente ab, die wie Swagger 2.0 aussehen.

Text (.txt), Markdown (.md) und JSON (.json) werden alle unterstützt - wählen Sie vor dem Download eines aus dem Format-Dropdown neben Download report. Der JSON-Export enthält die vollständige Liste der findings sowie Zählungen pro Severity, sodass er bei Bedarf in ein anderes Skript (z. B. eine CI-Prüfung) eingespeist werden kann.

Beides funktioniert: Drücken Sie Compare für einen sofortigen Neuvergleich, oder tippen Sie einfach weiter - nach einer kurzen Pause wird automatisch neu verglichen. Sie können auch von jedem Feld aus Ctrl+Enter (Cmd+Enter auf dem Mac) drücken, um sofort ohne Wartezeit zu vergleichen.