Emre Demir

Posted on Jun 2 • Originally published at apidog.com

OpenAPI Spezifikation mit Git versionieren

Ihre OpenAPI-Spezifikation ist ein Vertrag. Wenn sie sich ändert, können Clients brechen, Mocks veralten und Tests gegen eine API laufen, die nicht mehr existiert. Behandeln Sie die Spezifikation deshalb wie Code: in Git ablegen, über Branches ändern, per Pull Request prüfen und bei jeder Änderung validieren.

Probieren Sie Apidog noch heute aus

Dieser Leitfaden zeigt einen praxistauglichen Workflow für OpenAPI-Versionskontrolle mit Git: Ablageort der Datei, Branching, Review-Checkliste, CI-Validierung und wie Sie Änderungen direkt aus Apidog committen und pushen.

Warum Sie Ihre OpenAPI-Spezifikation versionieren sollten

Eine Spezifikation in einem Wiki oder freigegebenen Laufwerk hat keine belastbare Historie. Sie sehen nicht zuverlässig, wer den Payload von POST /orders geändert hat oder warum. Git löst genau dieses Problem.

Wenn Sie openapi.yaml unter Versionskontrolle legen, erhalten Sie:

Historie: Jede Änderung ist ein Commit mit Autor, Zeitstempel und Nachricht.
Verantwortlichkeit: git blame openapi.yaml zeigt, wer ein Feld hinzugefügt oder geändert hat.
Rollback: Ein fehlerhafter Merge lässt sich zurücksetzen.
Review: Spezifikationsänderungen laufen durch Pull Requests, bevor sie veröffentlicht werden.

Das ist die Grundlage eines Git-nativen API-Workflows: Die Spezifikation ist Quellcode, und Quellcode gehört in Git.

Wo die Spezifikationsdatei im Repository lebt

Halten Sie die Struktur einfach und vorhersehbar. Für viele Teams reicht eine einzelne Datei im Root-Verzeichnis oder in einem api/-Ordner:

my-service/
├── api/
│   └── openapi.yaml
├── src/
└── README.md

Wenn Sie mehrere Hauptversionen parallel pflegen, legen Sie pro Hauptversion eine eigene Datei an:

api/
├── api-v1.yaml
└── api-v2.yaml

So bleiben Breaking Changes isoliert. api-v1.yaml kann für bestehende Clients stabil bleiben, während api-v2.yaml weiterentwickelt wird. Außerdem werden Diffs kleiner und Reviews schneller, weil jede Datei einen klaren Zweck hat.

Diese Arbeitsweise entspricht der Idee von API-Spezifikation als Code.

Wichtig: Dokumentieren Sie die Konvention im Repository, zum Beispiel in der README.md. Vermeiden Sie mehrere Dateien, die gleichzeitig „die aktuelle Spezifikation“ sein sollen.

Branching-Strategien für Spezifikationsänderungen

Sie brauchen kein separates Branching-Modell nur für OpenAPI. Verwenden Sie denselben Prozess wie für Code:

Von main branchen.
Spezifikation ändern.
Pull Request öffnen.
Review und CI abwarten.
Mergen.

Eine einfache Namenskonvention macht API-Branches leichter erkennbar:

Branch-Typ	Muster	Beispiel
Neuer Endpunkt	`api/add-<resource>`	`api/add-refunds`
Feldänderung	`api/change-<resource>-<field>`	`api/change-order-status`
Breaking Change	`api/breaking-<description>`	`api/breaking-v2-auth`
Fix / Bereinigung	`api/fix-<description>`	`api/fix-pagination-schema`

Das Präfix api/ signalisiert sofort: Dieser PR ändert den API-Vertrag. Prüfer und CI-Jobs können danach filtern.

Bei Breaking Changes sollte der Branch-Name bewusst explizit sein, zum Beispiel api/breaking-v2-auth. Das erhöht die Sichtbarkeit und macht klar, dass wahrscheinlich eine neue Hauptversion oder Migration nötig ist.

Halten Sie Branches kurzlebig. Ein Spezifikations-Branch, der zwei Wochen offen bleibt, kollidiert schnell mit Änderungen anderer Teams. Kleine, fokussierte PRs lassen sich einfacher prüfen und mergen.

Spezifikationsänderungen im Pull Request prüfen

Ein OpenAPI-PR ist eine Vertragsänderung. Prüfen Sie ihn nicht nur auf gültiges YAML, sondern auf Auswirkungen für Clients.

Schreiben Sie YAML möglichst diff-freundlich:

paths:
  /orders/{orderId}:
    get:
      summary: Get an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

Praktische Regeln:

Konsistente Einrückung.
Eine Eigenschaft pro Zeile.
Stabile Reihenfolge für Felder.
Keine unnötige Neuformatierung ganzer Dateien.

So erscheint eine kleine Feldänderung auch als kleiner Diff.

Review-Checkliste

Prüfer sollten besonders auf diese Punkte achten:

Breaking Changes: Wurde ein Pflichtfeld hinzugefügt? Wurde ein Antwortfeld entfernt oder umbenannt? Hat ein Enum einen Wert verloren?
Abwärtskompatibilität: Neue optionale Felder und neue Endpunkte sind meist sicher. Änderungen an bestehenden Strukturen sind kritisch.
Benennung: Passen Pfade, Feldnamen, Groß-/Kleinschreibung und Pluralisierung zum Rest der API?
Vollständigkeit: Hat jede neue Operation eine summary, Antwort-Schemas und Fehlerantworten?
Beispiele: Gibt es realistische Request- und Response-Beispiele?
Statuscodes: Sind Erfolgs- und Fehlerfälle sauber modelliert?
Schemas: Werden bestehende Komponenten wiederverwendet, statt Duplikate zu erzeugen?

Verlassen Sie sich bei Breaking Changes nicht nur auf manuelle Reviews. Ein CI-Schritt sollte den PR gegen main vergleichen und inkompatible Änderungen automatisch markieren oder blockieren.

Committen und Pushen aus Apidog

Rohes YAML manuell zu bearbeiten funktioniert, ist aber fehleranfällig. Ein visueller Editor mit Live-Validierung kann Spezifikationsänderungen schneller und konsistenter machen.

Der Spec-First-Modus von Apidog unterstützt bidirektionale Git-Synchronisierung: Sie bearbeiten Endpunkte, Schemas und Beispiele in der Oberfläche, committen die Änderung und pushen sie in Ihr Repository. Änderungen von Teammitgliedern können Sie ebenfalls wieder aus Git ziehen.

Ein typischer Workflow:

Git-Repository mit Apidog verbinden.
Spezifikationsdatei auswählen, zum Beispiel api/openapi.yaml.
Endpunkte, Schemas oder Beispiele im visuellen Editor ändern.
Änderungen prüfen.
Auf einem Branch committen und pushen.
Pull Request wie gewohnt öffnen.

Da Apidog YAML konsistent serialisiert, bleiben Diffs kleiner und besser reviewbar. Die Einrichtung ist in den Apidog Spec-First Mode Docs beschrieben. Wenn Sie speziell nach GitHub synchronisieren möchten, siehe Synchronisierung Ihrer OpenAPI-Spezifikation mit GitHub.

CI-Validierungshooks

Lassen Sie keine ungültige Spezifikation nach main gelangen. Validieren Sie OpenAPI-Dateien automatisch in Pull Requests.

Ein minimaler GitHub-Actions-Workflow:

name: Validate OpenAPI

on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint spec
        run: npx @redocly/cli lint api/openapi.yaml

Erweitern Sie die Pipeline schrittweise:

Spezifikation linten.
Prüfen, ob sie als gültiges OpenAPI 3.x geparst werden kann.
Einen Diff gegen main ausführen.
Breaking Changes blockieren oder im PR markieren.
Optional generierte Artefakte prüfen, zum Beispiel Dokumentation oder SDKs.

Eine praktische Pipeline kann so aussehen:

name: Validate OpenAPI

on: [pull_request]

jobs:
  validate-openapi:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Lint OpenAPI spec
        run: npx @redocly/cli lint api/openapi.yaml

      - name: Fetch main
        run: git fetch origin main

      - name: Check for breaking changes
        run: |
          npx oasdiff breaking \
            base:api/openapi.yaml \
            revision:api/openapi.yaml

Passen Sie den Diff-Befehl an Ihr Tooling und Ihre Repository-Struktur an. Entscheidend ist: Die Prüfung läuft automatisch bei jedem Pull Request.

Best Practices

Diese Gewohnheiten halten die OpenAPI-Versionskontrolle langfristig wartbar:

Semantische Versionierung verwenden: Aktualisieren Sie info.version. Breaking Changes bedeuten eine neue Hauptversion.
Changelog führen: Ein kurzes CHANGELOG.md neben der Spezifikation hilft API-Konsumenten.
Kleine PRs liefern: Eine logische Änderung pro Pull Request.
Aussagekräftige Commit-Nachrichten schreiben: Add refundReason to refund request ist besser als update spec.
Nicht direkt auf main bearbeiten: Auch Tippfehler über Branch und PR korrigieren.
Breaking Changes explizit kennzeichnen: Im Branch-Namen, PR-Titel und Changelog.
Examples aktuell halten: Mocks und Dokumentation sind nur so gut wie die Beispiele in der Spezifikation.
CI verpflichtend machen: Linting und Breaking-Change-Erkennung sollten Required Checks sein.

FAQ

Wie erkenne ich Breaking Changes in einer OpenAPI-Spezifikation?

Führen Sie in der CI ein Spezifikations-Diff-Tool aus, das den Pull Request mit der Version auf main vergleicht. Tools wie oasdiff klassifizieren Änderungen als breaking, non-breaking oder unklassifiziert. Der Build kann fehlschlagen, wenn eine breaking Änderung erkannt wird.

Typische Breaking Changes sind:

Entfernte Antwortfelder.
Neue erforderliche Request-Felder.
Geänderte Datentypen.
Entfernte Enum-Werte.
Geänderte Pfade oder HTTP-Methoden.
Strengere Validierungsregeln.

Sollte ich eine OpenAPI-Datei behalten oder sie in mehrere aufteilen?

Beginnen Sie mit einer einzelnen openapi.yaml. Sie ist am einfachsten zu prüfen, zu versionieren und in CI zu validieren.

Teilen Sie erst auf, wenn es einen klaren Grund gibt:

Mehrere Hauptversionen parallel: api-v1.yaml, api-v2.yaml.
Sehr große Spezifikation.
Viele wiederverwendbare Schemas.
Mehrere Teams arbeiten an klar getrennten API-Bereichen.

Wenn Sie aufteilen, verwenden Sie konsistente $ref-Strukturen und dokumentieren Sie sie.

Kann ich meine Spezifikation versionieren, ohne YAML von Hand zu schreiben?

Ja. Der Spec-First-Modus von Apidog erlaubt das Bearbeiten der Spezifikation in einem visuellen Editor und die bidirektionale Synchronisierung mit Git. Dadurch behalten Sie Git-Historie, Pull-Request-Reviews und CI-Validierung, ohne jede Änderung manuell in YAML schreiben zu müssen.