Kennzeichnet, dass die API-Änderungen wahrscheinlich vor der Veröffentlichung beschädigt werden

Die zu erledigende Aufgabe

Erkennen Sie die Vertragsänderung, bevor es ein Kunde tut.

Eine OpenAPI-Datei kann sich in einem Pull-Request ändern, ohne dass jemand bemerkt, dass ein Antwortfeld verschwunden ist, ein Abfrageparameter erforderlich wurde oder eine Aufzählung einen Wert verloren hat. In einer langen Spezifikation verbergen sich Bearbeitungen wie diese zwischen Formatierungsänderungen und neuen Endpunkten.

Diff Anything vergleicht die freigegebene Spezifikation und den Kandidaten als geparste Dokumente im API-Schemamodus und kennzeichnet Änderungen, die seinen Breaking-Change-Regeln entsprechen, mit einem Regelcode. Die Etiketten geben Ihnen eine kurze Liste, die Sie zuerst lesen sollten. Die Entscheidung, ob Kunden betroffen sind, liegt bei Ihnen.

Empfohlener Pfad

Von der veröffentlichten Spezifikation zu einer überprüften Liste von Änderungen.

Verwenden Sie die Spezifikation, auf die Kunden heute angewiesen sind, als linke Seite und die vorgeschlagene Version als rechte Seite.

1. Öffnen Sie beide Spezifikationen

   Wählen Sie OpenAPI-, Swagger- oder JSON-Schemadateien aus, die in JSON oder YAML geschrieben sind. Automatisch erkennt sie anhand ihres Openapi-, Swagger- oder $schema-Schlüssels der obersten Ebene und öffnet den API-Schemamodus.

2. Lesen Sie das Urteil

   Ein Hinweis über dem Ergebnis gibt die Anzahl potenziell inkompatibler Änderungen an oder besagt, dass die Schemata gleichwertig sind. Wenn keine Regel zutrifft, werden Sie daran erinnert, dass weiterhin eine manuelle Vertragsprüfung erforderlich ist.

3. Filtern nach „Unterbrechung“.

   Wählen Sie „Unterbrechung“ im Bereichsfilter „Unterschiede“. Jeder Eintrag zeigt seinen Regelcode, z. B. API001 für einen entfernten Vorgang oder API004 für eine neue erforderliche Eingabe, und den Pfad der Änderung.

4. Lesen Sie, was die Regeln unbeschriftet lassen

   Wechseln Sie zurück zu „Alle“. Ein geändertes Muster oder ein umbenannter Parameter wird ohne Regelcode angezeigt, und durch das Einfügen eines Parameters können sich die Positionen der darauffolgenden Parameter verschieben.

5. Tor zum Gebäude

   Führen Sie mit Pro in der Microsoft Store-Version auf Windows --mode api --fail-on breaking aus oder legen Sie failOn: break für das Paar in einem Batch-Manifest fest, das JUnit oder SARIF schreibt. Identische Schemata sind erfolgreich und der Job schlägt nur bei fehlerhaften oder nicht klassifizierten Änderungen fehl.

Beteiligte Fähigkeiten

Wie die drei Funktionen zu einer API-Rezension passen.

Grenzen zu kennen

Lesen Sie die Etiketten als Ausgangspunkt.

Die Regeln beurteilen eine Änderung anhand ihrer Position im Dokument. Sie lösen $ref nicht auf und behandeln Anforderungs- und Antwortschemata nicht gleich, sodass einige markierte Elemente harmlos sind und einige kritische Änderungen, wie ein umbenannter Parameter, ein entfernter Komponenteneintrag oder hinzugefügte zusätzliche Eigenschaften: false, keinen Regelcode enthalten.

Ein erfolgreicher Lauf mit --fail-on breaking bedeutet, dass keine Regel angeschlagen hat. Er beweist nicht, dass Clients unbeeinträchtigt bleiben. Lassen Sie Änderungen, die die Regeln nicht beurteilen können, von einer Person prüfen.

Semantische Regeln wie „Pfade ignorieren“ gelten nicht im API-Schemamodus. Kostenlos zeigt vollständige API-Ergebnisse in der App innerhalb der Grenzen von 5 MB und 10 pro Tag; Für den API-Befehlszeilenmodus und Batch-Manifeste ist Pro erforderlich.

Zugehöriges Handbuch

Diff Anything mit Befehlszeile, Git und CI nutzen

Unter Windows Vergleiche wiederholbar ausführen, Exit-Codes verstehen, Git einbinden und maschinenlesbare Ergebnisse für CI erzeugen.

In den Abschnitten geht es darum, die installierte ausführbare Datei zu finden, den expliziten CLI-Modus aufzurufen, Exit-Codes zu interpretieren, die Ausgabe für den Verbraucher auszuwählen, Git Difftool zu konfigurieren, Diff für Git Diff zu verwenden, mit Git zusammenzuführen, Batch-Manifeste auszuführen und Automatisierungsfehler zu debuggen. Verwenden Sie es, wenn Sie bereit sind, diesen Workflow mit Ihren eigenen Projektdaten zu reproduzieren.

Direkte Antworten

Fragen zu diesem Anwendungsfall.