OpenAPI-Spezifikationen mit Git kontrollieren – so geht’s

Die OpenAPI-Spezifikation ist ein Vertrag zwischen Ihrem Backend und den Clients. Wenn sie nicht aktuell oder inkonsistent ist, funktionieren Mocks nicht mehr, Tests schlagen fehl – oder Sie deployen eine API, die es in dieser Form gar nicht gibt. Die Lösung? Behandeln Sie die Spezifikation wie Quellcode: versionieren Sie sie in Git, nutzen Sie Branches, führen Sie Pull Requests ein und validieren Sie jede Änderung vor dem Merge.

Warum Git für OpenAPI-Spezifikationen unverzichtbar ist

OpenAPI-Dokumente, die in Wikis oder Netzlaufwerken liegen, bieten keine verlässliche Historie. Sie können nicht nachvollziehen, wer wann ein Feld in POST /orders geändert hat – oder warum. Git löst dieses Problem, indem es die Spezifikation zu einem prüfbaren Artefakt macht.

Wenn Sie openapi.yaml in ein Git-Repository legen, profitieren Sie von:

• Änderungshistorie: Jede Modifikation wird als Commit mit Autor, Zeitstempel und Commit-Nachricht gespeichert.
• Blame-Funktion: Mit git blame openapi.yaml sehen Sie sofort, wer ein bestimmtes Endpoint oder Feld hinzugefügt hat.
• Rollback-Option: Falls ein Merge die API ungültig macht, können Sie den Commit einfach revertieren.
• Vorgängige Reviews: Änderungen an der Spezifikation durchlaufen einen Pull Request, sodass Kollegen die Diffs prüfen können, bevor sie gemergt werden.

Dieses Vorgehen folgt dem Prinzip des Git-native API Workflows, bei dem die Spezifikation als Quellcode behandelt wird – und Quellcode gehört ins Repository.

Wo speichert man OpenAPI-Dateien im Repository?

Beginnt mit einer einfachen und vorhersehbaren Struktur. Die meisten Teams platzieren die Datei openapi.yaml entweder im Projekt-Root oder in einem Ordner namens api/, zum Beispiel:

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

Falls Sie mehrere Major-Versionen parallel pflegen, trennen Sie die Dateien nach Version:

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

Diese Aufteilung bietet klare Vorteile:

• api-v1.yaml bleibt stabil für bestehende Clients.
• api-v2.yaml kann weiterentwickelt werden, ohne ältere Versionen zu beeinträchtigen.
• Diffs werden kürzer, da jede Datei nur die relevanten Änderungen enthält.
• Reviews konzentrieren sich auf die betroffene Version.

Dieses Konzept wird als API Spec as Code bezeichnet. Wichtig ist, eine Konvention festzulegen und diese in der Team-Dokumentation festzuhalten. Vermeiden Sie es, mehrere Dateien zu haben, die jeweils behaupten, die „offizielle“ Spezifikation zu sein.

Branching-Strategien für OpenAPI-Änderungen

Es ist nicht nötig, ein separates Branching-Modell für OpenAPI-Spezifikationen zu verwenden. Nutzen Sie denselben Workflow wie für Ihren Anwendungscode:

git checkout main
git pull
git checkout -b api/add-refunds
# Bearbeiten Sie api/openapi.yaml
git add api/openapi.yaml
git commit -m "Add refunds endpoint to OpenAPI spec"
git push origin api/add-refunds

Anschließend öffnen Sie einen Pull Request wie gewohnt.

Verwenden Sie aussagekräftige Branch-Namen, die den Typ der Änderung erkennen lassen:

• Neue Endpoints: api/add- (z. B. api/add-refunds)
• Feldänderungen: api/change- (z. B. api/change-order-status)
• Breaking Changes: api/breaking- (z. B. api/breaking-v2-auth)
• Bugfixes/Cleanup: api/fix- (z. B. api/fix-pagination-schema)

Das Präfix api/ signalisiert sofort, dass es sich um eine Änderung am API-Vertrag handelt. Zudem erleichtert es CI-Systemen oder Automatisierungstools, solche Branches zu filtern.

Bei Breaking Changes sollte der Branch-Name klar auf die Inkompatibilität hinweisen – etwa api/breaking-v2-auth – um Reviewer zu warnen und gegebenenfalls eine neue Major-Version zu planen.

Ein weiterer Tipp: Halten Sie Branches kurz und fokussiert. Ein Pull Request sollte immer nur eine logische Änderung enthalten. Langlebige Branches kollidieren oft mit anderen Änderungen und erschweren das Merge.

Pull Requests: Spezifikationen gründlich prüfen

Ein Pull Request für eine OpenAPI-Spezifikation ist keine Routineaufgabe – er verändert den API-Vertrag und sollte genauso gründlich geprüft werden wie Produktionscode.

Achten Sie darauf, dass die YAML-Datei lesbare Diffs erzeugt. Verwenden Sie konsistente Einrückungen und platzieren Sie jedes Property in einer separaten Zeile:

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

Das Ziel ist, dass ein Diff bei der Hinzufügung eines Felds nur die betreffenden Zeilen zeigt – nicht eine vollständige Neuanordnung der gesamten Datei.

Ein Review-Checklist für Kollegen umfasst:

• Breaking Changes: Wurden Required-Felder hinzugefügt? Feldnamen oder Response-Schemata entfernt? Wurden Enum-Werte gelöscht? Gab es Typ-Änderungen?
• Rückwärtskompatibilität: Neue Endpoints sind in der Regel sicher. Optional-Felder in bestehenden Schemata sind meist unbedenklich. Änderungen an bestehenden Schemata können jedoch riskant sein.
• Konsistenz bei Bezeichnungen: Werden Pfade im gleichen Stil wie andere API-Endpoints benannt? Wird Singular/Plural einheitlich verwendet? Entsprechen Feldnamen den Team-Konventionen?
• Vollständigkeit: Enthält jeder neue Operation eine summary? Sind Response-Schemata definiert? Gibt es Error-Responses?
• Beispiele: Sind Request- und Response-Beispiele realistisch genug für Dokumentation und Mocks?

Bei Breaking Changes reicht ein manuelles Review nicht aus. Integrieren Sie Tools in Ihre CI-Pipeline, die die PR-Spezifikation mit der main-Version vergleichen und den Build fehlschlagen lassen, wenn inkompatible Änderungen erkannt werden.

OpenAPI-Änderungen direkt aus Apidog committen

Manuelles Bearbeiten von YAML-Dateien funktioniert, ist aber fehleranfällig und langsam. Ein visueller Editor mit Echtzeit-Validierung beschleunigt den Prozess und reduziert Fehler.

Der Spec-First-Modus von Apidog unterstützt bidirektionale Git-Synchronisation:

• Verbinden Sie Ihr Git-Repository und wählen Sie die Spezifikationsdatei aus, z. B. api/openapi.yaml.
• Bearbeiten Sie Endpoints, Schemata, Parameter, Responses und Beispiele im visuellen Editor.
• Apidog schreibt die Änderungen als sauberes YAML zurück in die Datei.
• Committen Sie die Änderungen auf einem Branch und pushen Sie sie ins Repository.
• Öffnen Sie einen Pull Request für Review und Merge – wie im herkömmlichen Workflow.

Da Apidog die YAML-Struktur konsistent formatiert, bleiben Diffs klein und lesbar. Es gibt keine unnötigen Neuformatierungen oder Neuanordnungen, die den Review-Prozess erschweren.

Weitere Details finden Sie in der Apidog-Dokumentation zum Spec-First-Modus. Für eine direkte Anbindung an GitHub lesen Sie den Leitfaden OpenAPI-Spezifikationen mit GitHub synchronisieren.

CI-Validierung: Keine defekten Spezifikationen im Main-Branch

Lassen Sie niemals eine fehlerhafte OpenAPI-Spezifikation in den main-Branch gelangen. Integrieren Sie Validierungs-Checks in Ihre Pull-Request-Pipeline, sodass Vertragsverletzungen automatisch erkannt und der Build abgebrochen wird. Tools wie Spectral oder Swagger-Editor-CLI prüfen die Spezifikation auf Schema-Konformität, konsistente Bezeichnungen und Einhaltung von Best Practices.

Mit diesen Schritten stellen Sie sicher, dass Ihre OpenAPI-Spezifikation nicht nur aktuell, sondern auch vertrauenswürdig und teamübergreifend nutzbar bleibt. Die Zukunft der API-Entwicklung liegt im Spec-First-Ansatz – und Git ist das Rückgrat dieses Prozesses.

Der nächste Schritt? Automatisieren Sie die Validierung weiter, indem Sie Ihre CI-Pipeline um Tests ergänzen, die die API-Implementierung gegen die Spezifikation prüfen. So wird aus einem statischen Vertrag ein dynamisches Qualitätssicherungssystem.