Fügen Sie die frühere und neue Definition für einen Änderungsbericht ein. Prüfen Sie Auswirkungen auf Clients durch Vertragstests; externe Referenzen werden nicht geladen.
Läuft lokal in deinem BrowserKennzeichnungen für Breaking Changes konzentrieren sich auf entfernte Operationen oder Antworten und neu erforderliche Eingaben. Schemaänderungen werden zur Prüfung markiert, da ihre Kompatibilität von den Clients abhängt.
Nutzen Sie diesen Diff für eine schnelle Vertragsprüfung und bestätigen Sie die Auswirkungen anschließend in versionierten API-Tests. Externe Referenzen und Remote-Dateien werden von der lokalen Prüfung nicht aufgelöst.
Fügen Sie die veröffentlichte Spezifikation in „Earlier specification“ und den Entwurf in „Updated specification“ ein und drücken Sie die Vergleichsschaltfläche. Beide Felder nehmen JSON oder YAML an, und beide Dokumente bleiben im Browser: Nichts wird hochgeladen, abgerufen oder ausgeführt.
Das Ergebnis ist ein nach Schweregrad gegliederter Prüfbericht mit einem JSON Pointer pro Eintrag, sodass jeder Befund bis zur genauen Stelle im neuen Dokument zurückverfolgt werden kann.
Eine entfernte Operation, ein entfernter Pflichtparameter, ein optionaler Parameter, der Pflicht wurde, ein neu hinzugekommener Pflichtparameter und ein nun Pflicht gewordenes Request-Body werden als DANGER geführt. Ebenso ein entfernter Response-Status und ein entfernter Request-Content-Type, weil bestehende Aufrufer davon abhängen können.
Schemaänderungen werden als WARNING statt als DANGER gemeldet, weil ein Bruch vom jeweiligen Client abhängt: geänderte Parameter-, Request- und Response-Schemas, entfernte oder bearbeitete Komponenten-Schemas sowie entfernte optionale Parameter. Das Bearbeiten einer gemeinsam genutzten Komponente wird unter /components/schemas/<Name> gemeldet — dort, wo eine generierte Definition ihre brechende Änderung meist trägt.
Beim Schemavergleich werden die Schlüsselwörter required, enum, type, allOf, anyOf und oneOf als Mengen behandelt; ein neu generiertes Dokument, das sie nur umsortiert, wird daher nicht als Änderung gemeldet.
Operationen werden über Methode und Pfad zugeordnet. Ein umbenannter Pfadparameter erscheint deshalb als eine entfernte plus eine hinzugefügte Operation und nicht als einzelne Änderung. Verweise innerhalb desselben Dokuments (#/components/...) werden vor dem Vergleich aufgelöst; externe und entfernte Verweise werden nicht abgerufen, ein Parameter oder Schema, das nur in einer anderen Datei existiert, wird also so verglichen, wie es dasteht.
Swagger-2.0-Dokumente werden genauso verglichen, weil Pfade, Operationen, Parameter und Responses gleich gelesen werden. Servers, Sicherheitsanforderungen, Tags, Beschreibungen und Beispiele werden nicht verglichen.
Jeder Eintrag trägt einen Schweregrad (DANGER, WARNING, INFO oder GOOD), den JSON Pointer des betroffenen Elements und einen Satz zur Änderung. In einem Pointer steht ~1 für einen Schrägstrich innerhalb eines Pfades, /paths/~1users/get ist also GET /users.
Ein leeres Feld wird als solches gemeldet, und ein Dokument, das kein gültiges JSON oder YAML ist, wird mit der fehlerhaften Zeile abgelehnt — ein kaputtes Einfügen sieht damit nie wie ein sauberer Vergleich aus.