OpenAPI Diff

Was dieser Differ prüft — und was Breaking wirklich bedeutet

Eine Änderung ist Breaking, wenn ein Client, der korrekt gegen die alte Spezifikation geschrieben wurde, gegen die neue scheitern kann, ohne eine Zeile seines eigenen Codes zu ändern. Diese Definition treibt jedes Urteil auf dieser Seite. Einen Pfad oder eine Operation zu entfernen ist Breaking, weil bestehende Aufrufe kein Ziel mehr haben. Einen Antwortstatus zu entfernen — vor allem einen 2xx — ist Breaking, weil die Fehlerbehandlung des Clients um die alte Menge herum geschrieben wurde. Einen Pflichtparameter oder eine Pflicht-Anfrageeigenschaft hinzuzufügen ist Breaking, weil die gestern gültige Anfrage plötzlich abgelehnt wird. Den Typ oder das Format eines Felds zu ändern ist Breaking, weil Parser, Validatoren und generierte SDKs alle auf dem deklarierten Typ aufbauen. Einen Enum-Wert zu entfernen ist Breaking, weil ein Client ihn noch senden oder Daten speichern kann, die er nicht mehr interpretieren kann. Alles andere — ein neuer Endpunkt, ein optionaler Parameter, ein neues Antwortfeld, ein neuer Enum-Wert, ein neuer Statuscode — wird als nicht Breaking berichtet: Alte Clients funktionieren weiter, auch wenn sie die neue Fähigkeit noch nicht nutzen können.

Der Vergleich ist strukturell, nicht textuell. Beide Dokumente werden in dasselbe Modell normalisiert, bevor irgendetwas verglichen wird: jeder Pfad und jede Operation, ihre nach Name und Ort indizierten Parameter, ihr Anfragekörper und jede Antwort, reduziert auf eine Schema-Signatur — eine deterministische Zusammenfassung von Typen, Formaten, Eigenschaftsnamen, Pflichtlisten und Enum-Werten, rekursiv aufgebaut und mit aufgelösten lokalen $ref-Referenzen. Deshalb erzeugen das Umordnen von Schlüsseln, das Neuformatieren von Leerzeichen oder das Umschreiben jeder Beschreibung einen leeren Diff: Nichts davon ändert den Vertrag. Und deshalb wird auch eine Änderung gefunden, die drei Ebenen tief in einem referenzierten Schema vergraben ist — die Signatur expandiert die Referenz, statt nur ihren Namen zu vergleichen.

Zwei Eingabeformen werden akzeptiert, weil das Ökosystem beide veröffentlicht: Zuerst wird JSON versucht, und wenn das scheitert, wird der Text als YAML geparst, das Format, das die meisten handgeschriebenen OpenAPI-Dokumente verwenden. Auch Swagger-2.0-Dokumente funktionieren, einschließlich ihrer in: body-Parameter und der Schemata pro Antwort. Absichtlich gibt es kein Live-Abrufen und kein Hochladen: Fügen Sie die Dokumente ein oder legen Sie die Dateien ab, genau wie bei einer HAR-Aufzeichnung, und der Vergleich läuft, wenn Sie die Schaltfläche drücken — nicht bei jedem Tastenschlag —, sodass zwei große eingefügte Spezifikationen reaktionsschnell bleiben.

Nutzen Sie das Ergebnis als Freigabeschranke, nicht als Dekoration. In einer Prüfung ist die Breaking-Liste die Tagesordnung: Jeder Eintrag braucht entweder eine Korrektur, eine Versionsanhebung, ein Deprecation-Fenster oder eine schriftliche Entscheidung, dass der Bruch beabsichtigt und kommuniziert ist. Die Nicht-Breaking-Liste ist der Entwurf des Änderungsprotokolls. Den Diff als JSON zu exportieren erlaubt es, diese Entscheidung neben dem Release zu archivieren, und die kopierbare Zusammenfassung passt direkt in einen Pull Request — dieselbe Disziplin, die Sie auf eine Vertragsänderung bei einem Webhook anwenden würden, bei der eine still geänderte Nutzlast jeden Abonnenten auf einmal bricht.

Ehrliche Grenzen, klar benannt. Dieser Differ vergleicht den deklarierten Vertrag: Er kann kein Verhalten sehen, das die Spezifikation nicht deklariert — etwa ein Feld, das seinen Typ behält, aber seine Bedeutung ändert, eine neue Geschäftsregel, strengere Rate Limits oder eine Fehlermeldung, die Clients (unklugerweise) geparst haben. Er folgt lokalen Referenzen und vergleicht Schemata bis zu einer begrenzten Tiefe, sodass pathologisch tief verschachtelte oder gegenseitig rekursive Schemata zusammengefasst statt endlos expandiert werden. Und ein Diff mit null Breaking Changes ist kein Versprechen, dass ein Upgrade sicher ist — es ist der Nachweis, dass der dokumentierte Vertrag gehalten hat, und genau das ist der Nachweis, den man vor dem Deployment haben sollte.