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

Direkte Antwort

Kann Diff Anything wichtige OpenAPI-Änderungen erkennen?

Diff Anything vergleicht das OpenAPI- und das JSON-Schema als analysierte Verträge und kennzeichnet wahrscheinlich inkompatible Änderungen mit heuristischen Regelcodes, wie z. B. einen entfernten Vorgang oder eine neue erforderliche Eingabe. Mit Pro auf Windows führen CLI und Batch-Manifeste den gleichen Vergleich in CI durch: identische Schemata werden bestanden, und --fail-on breaking schlägt den Job nur bei Breaking- oder nicht klassifizierten Änderungen fehl, wobei der Regelcode jedes Ergebnisses in JUnit und SARIF enthalten ist. Die Regeln sind heuristisch, sodass gekennzeichnete und bestandene Ergebnisse noch einer Vertragsprüfung bedürfen.

Unterstützte Schemata

OpenAPI, JSON Schema, GraphQL und SQL-Tabellen.

Der API-Schemamodus vergleicht OpenAPI- und JSON-Schemadokumente, die in JSON oder YAML geschrieben wurden. Erkennt sie automatisch anhand von Schlüsseln der obersten Ebene wie openapi, swagger oder $schema. Derselbe Modus liest auch GraphQL-Typ-, Schnittstellen- und Eingabedefinitionen sowie SQL CREATE TABLE-Anweisungen.

Jede Änderung wird mit ihrem Speicherort aufgelistet, zum Beispiel $.paths["/users"].get.parameters[0]. Wenn die beiden Seiten in unterschiedlichen Schemasprachen geschrieben sind, besagt das Ergebnis, dass die Klassifizierung nur strukturell ist.

Breaking-Change-Regeln

Wahrscheinlich inkompatible Änderungen werden mit einem Regelcode gekennzeichnet.

Jeder Unterschied wird anhand einer Reihe von Kompatibilitätsregeln überprüft. Eine Übereinstimmung erhält mit ihrem Regelcode die Bezeichnung „Breaking API change“ und der Breaking-Filter in der Differenzliste zeigt nur diese Elemente an. Ein Hinweis über dem Ergebnis gibt das Urteil an, z. B. „2 potenziell störende API-Änderungen, die durch heuristische Regeln erkannt wurden“. Identische oder äquivalente Schemata, einschließlich des gleichen Schemas, das einmal in JSON und einmal in YAML geschrieben wurde, melden keine Unterschiede.

• API001: Eine Operation, ein Parameter, eine Antwort oder ein Pfad wurde entfernt
• API002: Ein Feld, eine Spalte oder ein Typmitglied wurde entfernt
• API003: Ein Wert wurde aus einer Aufzählung, oneOf oder anyOf entfernt
• API004: Eine neue erforderliche Eingabe wurde hinzugefügt
• API005: Ein optionaler oder nullbarer Wert wurde erforderlich
• API006 und API007: Eine minimale oder maximale Einschränkung wurde strenger
• API008: Sicherheitsanforderungen wurden hinzugefügt oder geändert
• API009: Der Typ, das Format oder die $ref eines Schemas hat sich geändert, oder ein Wert in seinen Eigenschaften hat seine Art geändert
• API010: Eine GraphQL-Feldsignatur oder SQL-Spaltendefinition wurde geändert

Wie man es liest

Behandeln Sie die Klassifizierung als Überprüfungshilfe.

Die Regeln prüfen, wo sich eine Änderung im Dokument befindet. Sie unterscheiden nicht zwischen Anforderungsschemata und Antwortschemata, sodass eine neue erforderliche Antworteigenschaft auf die gleiche Weise gekennzeichnet wird wie ein neues erforderliches Anforderungsfeld. Referenzen ($ref) werden im geschriebenen Zustand verglichen und nicht aufgelöst: Eine geänderte Referenz wird unter API009 gekennzeichnet, aber das Schema, auf das sie verweist, wird nicht verglichen. Änderungen an Schlüsselwörtern wie „Muster“ werden ohne Regelcode aufgeführt. Das Entfernen eines gesamten Eintrags unter „Komponenten“, das Umbenennen oder Verschieben eines Parameters, das Hinzufügen von „additionalProperties: false“ und das Entfernen von Sicherheitsanforderungen werden nicht als fehlerhaft eingestuft.

Arrays wie Parameter werden nach Position verglichen, sodass beim Einfügen eines Parameters auch Änderungen an späteren Positionen angezeigt werden können. Lesen Sie jedes markierte Element, bevor Sie entscheiden, ob Kunden betroffen sind. Das Ergebnis besagt dasselbe: Wenn keine Regel zutrifft, ist weiterhin eine manuelle Vertragsprüfung erforderlich.

CI Tor

Ein CI-Job schlägt nur bei Breaking Changes mit Pro fehl.

Mit Pro auf Windows führt --mode api den Vergleich über die Befehlszeile mit Zusammenfassung, Terminal oder JSON-Ausgabe aus. Fügen Sie --fail-on breaking hinzu und der Befehl gibt nur dann 1 zurück, wenn eine Änderung fehlerhaft ist oder nicht klassifiziert werden konnte; Identische Schemata und nicht unterbrechende Änderungen geben 0 zurück.

Legen Sie in einem Batch-Manifest failOn: break für einen API-Fall fest. Die JUnit-Ausgabe listet die Breaking Changes mit ihren Regelcodes auf, und SARIF meldet jedes Ergebnis als eigenes Ergebnis, wobei Breaking Changes unter ihrem Regelcode als Fehler gemeldet werden. Die Regeln sind heuristisch, daher betrachten Sie einen bestandenen Scheck als erstes Tor und nicht als Beweis dafür, dass Kunden nicht betroffen sind.

Am besten für

Wo dieser Workflow passt.

• Überprüfen einer OpenAPI- oder JSON-Schemaänderung, bevor sie für Kunden freigegeben wird
• Erhalten einer ersten Liste wahrscheinlicher Änderungen, die manuell überprüft werden müssen
• Vergleich der API-Definitionen, die auf Ihrem eigenen Computer verbleiben müssen

Keine Konten, Cloud-Vergleichsdienst, Analysen oder Telemetrie.

Relevante Fähigkeiten

Was Diff Anything für den Job bringt.

Praktischer Arbeitsablauf

Vom Setup zum überprüften Ergebnis.

1. Öffnen Sie die freigegebenen und Kandidatenspezifikationen

   Wählen Sie die beiden Schemadateien OpenAPI oder JSON. Automatisch öffnet sie im API-Schemamodus.

2. Filtern nach „Unterbrechung“.

   Verwenden Sie den Breaking-Filter, um zuerst die Änderungen anzuzeigen, die einer Kompatibilitätsregel entsprachen.

3. Überprüfen Sie jede markierte Änderung

   Lesen Sie den Regelcode und den Speicherort und entscheiden Sie dann, ob er sich auf Anfragen, Antworten oder keines von beiden auswirkt.

4. Überprüfen Sie die verbleibenden Änderungen

   Wechseln Sie zurück zu „Alle“, um Änderungen zu überprüfen, die von den Regeln nicht klassifiziert werden, z. B. Musteränderungen oder ein umbenannter Parameter.

Nützlich in der Praxis

Direkte Antworten

Fragen zum OpenAPI-Diff-Tool.

Gehen Sie tiefer

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

Weiterführende Anleitungen

Verstehen Sie den Arbeitsablauf aus einem anderen Blickwinkel.