OpenAPI vergleichen

OpenAPI Diff

Vergleicht zwei OpenAPI-Dokumente und trennt Breaking Changes von additiven Änderungen.

Vergleicht zwei Versionen eines OpenAPI-Dokuments und teilt die Änderungen in brechende und ergänzende. Die verwendete Regel steht auf der Seite: Eine Änderung ist brechend, wenn eine Anfrage, die das alte Dokument akzeptiert hat, jetzt abgelehnt werden könnte, oder eine Antwort, die es versprochen hat, eine ist, mit der ein bestehender Client nicht mehr umgehen kann.

🔒 Läuft vollständig in Ihrem Browseropenapidiffapibreaking-change

Vorheriges Dokument

openapi: 3.0.3
info: { title: Pets API, version: "1.0.0" }
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Pet" }
  /pets/{id}:
    get:
      operationId: getPet
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
        "404": { description: Not found }
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id: { type: integer }
        name: { type: string }
        status: { type: string, enum: [available, sold] }

Die vorherige Version hier ablegen

Wird nur in diesem Tab gelesen.

Neues Dokument

openapi: 3.0.3
info: { title: Pets API, version: "2.0.0" }
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets, paginated
      parameters:
        - name: limit
          in: query
          required: true
          schema: { type: integer }
        - name: sort
          in: query
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Pet" }
  /pets/{petId}:
    get:
      operationId: getPet
      parameters:
        - { name: petId, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
    delete:
      operationId: deletePet
      parameters:
        - { name: petId, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: Deleted }
components:
  schemas:
    Pet:
      type: object
      required: [id]
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string, enum: [available, sold, pending] }
        owner: { $ref: "#/components/schemas/Owner" }
    Owner:
      type: object
      properties:
        name: { type: string }

Die neue Version hier ablegen

Wird nur in diesem Tab gelesen.

Brechend

Additiv

Urteil

Braucht eine Major-Version

GET /pets

brechendJetzt ist der `in: query`-Parameter `limit` erforderlich.
hinzugefügtEin optionaler `in: query`-Parameter `sort` wurde hinzugefügt.
geändertDie Zusammenfassung oder die Beschreibung hat sich geändert.

GET /pets · responses["200"].content["application/json"]

brechend`[].id` hat den Typ von integer auf string geändert.
brechendDie Eigenschaft `[].name` ist jetzt optional.
brechend`[].status` hat den enum-Wert "pending" dazubekommen.
hinzugefügtEine optionale Eigenschaft `[].owner` wurde hinzugefügt.

GET /pets/{petId} · responses["200"].content["application/json"]

brechend`id` hat den Typ von integer auf string geändert.
brechendDie Eigenschaft `name` ist jetzt optional.
brechend`status` hat den enum-Wert "pending" dazubekommen.
hinzugefügtEine optionale Eigenschaft `owner` wurde hinzugefügt.

GET /pets/{petId}

brechendDie `404`-Antwort ist verschwunden.

DELETE /pets/{petId}

hinzugefügtDie Operation wurde hinzugefügt.

components.schemas.Owner

hinzugefügtDas Schema wurde hinzugefügt.

info.version

geändert`1.0.0` → `2.0.0`

Was als brechend gilt

In einem Satz: eine Anfrage, die das vorherige Dokument angenommen hat, könnte jetzt abgelehnt werden, oder eine Antwort, die es versprochen hat, ist eine, die ein bestehender Client nicht mehr verarbeiten kann. Also: einen Pfad, eine Operation, einen Antwortcode, einen Medientyp oder eine Antworteigenschaft entfernen; einen erforderlichen Parameter oder eine erforderliche Anfrageeigenschaft hinzufügen; optional wird erforderlich; eine Typänderung; einen Wert aus einem Anfrage-Enum entfernen; einen Wert zu einem Antwort-Enum hinzufügen (der switch des Clients hat keinen case dafür); und eine Antworteigenschaft, die von erforderlich zu optional wird. Die Gegenrichtungen sowie Änderungen an Beschreibungen, Tags, operationId und deprecated-Markierungen sind kompatibel.

· Schemas werden verglichen, nachdem den $ref innerhalb des Dokuments gefolgt wurde, deshalb ist das Umbenennen einer Komponente keine Änderung. Pfadparameter werden nach Position und nicht nach Namen zugeordnet.
· Das Innere von oneOf·anyOf·not wird als Ganzes verglichen und bei Unterschieden als brechend gemeldet — darüber wird hier nicht nachgedacht.
· Einem $ref, der auf eine andere Datei zeigt, wird nicht gefolgt. Bündeln Sie die Dateien zuerst zu einer.

Um ein einzelnes Dokument zu prüfen, nehmen Sie OpenAPI-Prüfung.

So funktioniert es

Stellen Sie das alte und das neue Dokument nebeneinander
JSON oder YAML für beide. Beide werden in diesem Tab geparst, sodass eine unveröffentlichte Spezifikation Ihre Maschine nicht verlässt.
Lesen Sie das Urteil
Zahl der brechenden, Zahl der ergänzenden Änderungen und was das für die Versionsnummer bedeutet: ein Major-Sprung, ein Minor-Sprung oder gar nichts, weil der Vertrag unverändert ist.
Filtern Sie auf die brechenden und lesen Sie sie
Gruppiert nach Operation, jede mit dem, was sich geändert hat. Die Markdown-Kopie ist für eine Pull-Request-Beschreibung geformt.

Häufige Fragen

Warum ist das Hinzufügen eines Enum-Werts in einer Antwort brechend?

Weil ein bestehender Client ein switch ohne Fall dafür hat. Etwas zu einem *Anfrage*-Enum hinzuzufügen ist sicher – der Server akzeptiert mehr als zuvor; etwas zu einem Antwort-Enum hinzuzufügen schickt Clients etwas, von dem ihnen nie erzählt wurde. Die Richtung ist es, was entscheidet.

Ich habe eine Komponente umbenannt, und es meldet keine Änderung.

Richtig. Schemas werden nach dem Auflösen von `$ref` verglichen, sodass eine umbenannte Komponente mit derselben Form derselbe Vertrag ist. Namen in `components` sind intern; Clients sehen die aufgelöste Form.

Ist es wirklich brechend, wenn eine erforderliche Antwort-Property optional wird?

Ja, aus Sicht des Clients. Ihm wurde versprochen, dass das Feld immer da ist, und sein Code liest es bedingungslos; es optional zu machen heißt, der Server darf es jetzt weglassen. Erforderlich und optional tauschen zwischen Anfrage und Antwort die Richtung, und das ist der Teil, den man verkehrt herum im Kopf hat.

Wie geht es mit `oneOf` und `anyOf` um?

Sie werden als Ganzes verglichen und als brechend gemeldet, wenn sie sich überhaupt unterscheiden. Zu entscheiden, ob eine Union eine Obermenge einer anderen ist, ist ein Entscheidungsverfahren, das hier absichtlich nicht versucht wird; ein falsches „brechend“, das Sie abtun können, ist besser als ein falsches „sicher“, das Sie nicht abtun können.

Eingabe aus

JSON vergleichen

JSON Diff

Vergleicht zwei JSON-Dokumente strukturell, ignoriert die Schlüsselreihenfolge und meldet hinzugefügte, entfernte und geänderte Pfade.

Läuft vollständig in Ihrem Browser

OpenAPI-Linter

OpenAPI Linter

Prüft ein OpenAPI-Dokument auf fehlende Antworten, ungenutzte Schemas, ins Leere zeigende Referenzen und die anderen Mängel, die Codegeneratoren brechen.

Läuft vollständig in Ihrem Browser

Semver-Bereichstester

Semver Range Tester

Prüft, welche Versionen einen Bereich erfüllen, vergleicht zwei Versionen und sortiert eine Liste nach Vorrang.

Läuft vollständig in Ihrem Browser

JSON formatieren und validieren

JSON Formatter & Validator

Formatiert, minimiert und validiert JSON und zeigt bei Syntaxfehlern die genaue Zeile und Spalte.

Läuft vollständig in Ihrem Browser

Danach

Diese Tools nehmen an, was dieses hier erzeugt, das Ergebnis kann also direkt weiter.

JSON vergleichen

JSON Diff

Vergleicht zwei JSON-Dokumente strukturell, ignoriert die Schlüsselreihenfolge und meldet hinzugefügte, entfernte und geänderte Pfade.

Läuft vollständig in Ihrem Browser

JSON-Schema-Validator

JSON Schema Validator

Validiert ein Dokument gegen ein JSON Schema und meldet jeden Fehler mit seinem Instanzpfad.

Läuft vollständig in Ihrem Browser

OpenAPI-Linter

OpenAPI Linter

Prüft ein OpenAPI-Dokument auf fehlende Antworten, ungenutzte Schemas, ins Leere zeigende Referenzen und die anderen Mängel, die Codegeneratoren brechen.

Läuft vollständig in Ihrem Browser

Semver-Bereichstester

Semver Range Tester

Prüft, welche Versionen einen Bereich erfüllen, vergleicht zwei Versionen und sortiert eine Liste nach Vorrang.

Läuft vollständig in Ihrem Browser

JSON ⇄ CSV umwandeln

JSON ⇄ CSV

Flacht verschachteltes JSON zu Spalten ab oder baut Objekte aus einer Tabelle wieder auf, mit Punktpfad-Regel für die Spaltennamen.

Läuft vollständig in Ihrem Browser

JSON formatieren und validieren

JSON Formatter & Validator

Formatiert, minimiert und validiert JSON und zeigt bei Syntaxfehlern die genaue Zeile und Spalte.

Läuft vollständig in Ihrem Browser