OpenAPI Spezifikation mit Git versionieren

Ihre OpenAPI-Spezifikation ist ein Vertrag. Wenn sie sich ändert, funktionieren Clients nicht mehr, Mocks veralten und Tests laufen gegen eine API, die nicht mehr existiert. Behandeln Sie die Spezifikation daher wie den Rest Ihres Codes: Legen Sie sie in Git ab, verzweigen Sie sie, überprüfen Sie sie und validieren Sie sie bei jeder Änderung.

Dieser Leitfaden führt Sie von Grund auf durch die OpenAPI-Versionskontrolle mit Git. Wo die Datei abgelegt wird, wie man verzweigt, worauf Prüfer in einem Spezifikations-Diff achten und wie man Änderungen direkt aus Apidog pusht. Am Ende verfügen Sie über einen Workflow, dem Ihr gesamtes Team vertrauen kann.

App herunterladen

Warum Sie Ihre OpenAPI-Spezifikation versionieren sollten

Eine Spezifikation, die in einem Wiki oder einem freigegebenen Laufwerk liegt, hat keine Historie. Sie können nicht sehen, wer den POST /orders Payload letzten Dienstag geändert hat oder warum. Git behebt das.

Legen Sie openapi.yaml unter Versionskontrolle und Sie erhalten vier Dinge kostenlos:

• Historie. Jede Änderung ist ein Commit mit einem Autor, einem Zeitstempel und einer Nachricht.
• Verantwortlichkeit. git blame openapi.yaml sagt Ihnen, wer dieses erforderliche Feld wann hinzugefügt hat.
• Rollback. Ein fehlerhafter Merge, der den Vertrag gebrochen hat? Machen Sie den Commit rückgängig und Sie haben wieder eine funktionierende Spezifikation.
• Überprüfung. Spezifikationsänderungen durchlaufen Pull Requests, sodass eine zweite Person den Unterschied sieht, bevor er veröffentlicht wird.

Dies ist die Grundlage eines Git-nativen API-Workflows: Die Spezifikation ist Quellcode, und Quellcode lebt in Git.

Wo die Spezifikationsdatei im Repository lebt

Halten Sie es einfach und vorhersehbar. Die meisten Teams legen eine einzelne openapi.yaml im Root-Verzeichnis des Repositorys oder in einem api/-Ordner ab:

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

Wenn Sie mehrere Hauptversionen parallel pflegen, teilen Sie diese nach Versionen auf, mit einer Datei pro Hauptversion:

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

Dies hält bahnbrechende Änderungen isoliert. api-v1.yaml bleibt für bestehende Clients eingefroren, während sich api-v2.yaml weiterentwickelt. Es macht auch Diffs kleiner und die Überprüfung schneller, da sich jede Datei aus einem bestimmten Grund ändert. Die Behandlung der Spezifikation auf diese Weise ist die Kernidee hinter API-Spezifikation als Code.

Wählen Sie eine Konvention und dokumentieren Sie diese. Das schlimmste Ergebnis sind zwei Dateien, die behaupten, „die“ Spezifikation zu sein.

Branching-Strategien für Spezifikationsänderungen

Sie benötigen kein spezielles Branching-Modell für Spezifikationen. Verwenden Sie, was Ihr Code bereits tut. Verzweigen Sie von main, nehmen Sie die Änderung vor, öffnen Sie einen PR.

Namenskonvention, die Spezifikations-Branches leicht lesbar hält:

Das Präfix api/ signalisiert auf einen Blick: „Dieser PR berührt den Vertrag“. Prüfer und CI können danach filtern. Bei Breaking Changes ist das explizite Präfix breaking- ein Hinweis darauf, dass hier zusätzliche Aufmerksamkeit und wahrscheinlich eine Versionserhöhung erforderlich ist.

Halten Sie Branches kurzlebig. Ein Spezifikations-Branch, der zwei Wochen lang existiert, kollidiert mit den Änderungen aller anderen. Kleine, fokussierte Branches lassen sich sauber zusammenführen.

Überprüfung von Spezifikationsänderungen in einem Pull Request

Hier macht sich die Versionskontrolle bezahlt. Ein Spezifikations-PR ist eine Vertragsänderung, und Vertragsänderungen verdienen eine echte Überprüfung.

Schreiben Sie YAML auf eine Diff-freundliche Weise, damit Prüfer die Änderung lesen können und nicht mit der Formatierung kämpfen müssen:

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"

Konsistente Einrückung und eine Eigenschaft pro Zeile bedeuten, dass eine einzeilige Feldeinfügung als einzeiliger Diff angezeigt wird. Das ist das Ziel.

Was Prüfer überprüfen sollten:

• Breaking Changes. Wurde ein erforderliches Feld zu einer Anfrage hinzugefügt? Wurde ein Antwortfeld entfernt oder umbenannt? Hat ein Enum einen Wert verloren? Jedes davon kann bestehende Clients beschädigen.
• Abwärtskompatibilität. Neue optionale Felder und neue Endpunkte sind sicher. Änderungen an bestehenden Strukturen sind es nicht.
• Benennung und Konsistenz. Entspricht der neue Endpunkt der Groß-/Kleinschreibung und Pluralisierung des Rests der API?
• Vollständigkeit. Jede neue Operation benötigt eine summary, Antwort-Schemas und Fehlerantworten.
• Beispiele. Realistische Beispiele machen die Dokumentation und Mocks nützlich.

Verlassen Sie sich bei der Erkennung von Breaking Changes eher auf Tools als auf menschliche Augen. Ein CI-Schritt (unten behandelt) kann die Spezifikation des PRs mit main vergleichen und den Build fehlschlagen lassen, wenn er eine inkompatible Änderung feststellt. Menschen übersehen diese; Diff-Tools nicht.

Committen & pushen von Apidog

Das manuelle Bearbeiten von rohem YAML funktioniert, aber ein visueller Editor mit Live-Validierung ist schneller und fängt Fehler früher ab. Apidog's Spec-First Modus bietet Ihnen eine bidirektionale Git-Synchronisierung: Bearbeiten Sie die Spezifikation in der Benutzeroberfläche, committen und pushen Sie sie in Ihr Repository, ohne das Tool zu verlassen. Ziehen Sie die Änderungen eines Teamkollegen auf die gleiche Weise zurück.

Der Workflow sieht folgendermaßen aus:

1. Verbinden Sie Ihr Git-Repository und verweisen Sie Apidog auf die Spezifikationsdatei.
2. Bearbeiten Sie Endpunkte, Schemas und Beispiele im visuellen Editor.
3. Apidog schreibt sauberes, diff-freundliches YAML zurück in die Datei.
4. Committen Sie auf einem Branch und pushen Sie, dann öffnen Sie Ihren PR wie gewohnt.

Da Apidog YAML konsistent serialisiert, bleiben Ihre Diffs klein und überprüfbar, ohne unnötige Neuordnung oder Neuformatierung. Die vollständige Einrichtung können Sie in den Apidog Spec-First Mode Docs nachlesen. Wenn die Datei bei einem bestimmten Anbieter landen soll, siehe Synchronisierung Ihrer OpenAPI-Spezifikation mit GitHub.

CI-Validierungshooks

Lassen Sie niemals eine ungültige Spezifikation in main gelangen. Integrieren Sie die Validierung in Ihre Pull-Request-Prüfungen, sodass ein gebrochener Vertrag den Build automatisch fehlschlagen lässt.

Ein minimaler GitHub Actions-Schritt:

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

Fügen Sie weitere Prüfungen hinzu, wenn Sie wachsen:

• Linten Sie die Spezifikation auf strukturelle und Stilprobleme.
• Validieren Sie, dass sie als gültiges OpenAPI 3.x geparst wird.
• Führen Sie einen Diff gegen main durch, um Breaking Changes zu erkennen und diese im PR zu kennzeichnen.

Diese Prüfungen laufen in Sekundenschnelle ab und fangen Fehler ab, die ein menschlicher Prüfer übersehen würde.

Best Practices

Einige Gewohnheiten sorgen dafür, dass die Spezifikations-Versionskontrolle auf Dauer gesund bleibt:

• Verwenden Sie semantische Versionierung. Erhöhen Sie das Feld info.version. Ein Breaking Change bedeutet eine neue Hauptversion; abwärtskompatible Ergänzungen erhöhen die Nebenversion.
• Führen Sie ein Changelog. Ein kurzes CHANGELOG.md neben der Spezifikation informiert Konsumenten über Änderungen zwischen den Versionen.
• Liefern Sie kleine Diffs. Eine logische Änderung pro PR. Große Spezifikations-PRs verbergen Breaking Changes im Rauschen.
• Schreiben Sie aussagekräftige Commit-Nachrichten. „Füge refundReason zur Rückerstattungsanfrage hinzu“ ist besser als „update spec.“
• Bearbeiten Sie die zusammengeführte Spezifikation niemals direkt auf main. Immer verzweigen, selbst bei einem Tippfehler.

FAQ

Wie erkenne ich Breaking Changes in einer OpenAPI-Spezifikation?

Führen Sie in Ihrer CI ein Spezifikations-Diff-Tool aus, das den Pull Request mit der Version auf main vergleicht. Tools wie oasdiff klassifizieren jede Änderung als breaking, non-breaking oder unklassifiziert und können den Build bei einer breaking Änderung fehlschlagen lassen. Dies fängt entfernte Felder, neue erforderliche Parameter und geänderte Typen ab, die bei einer manuellen Überprüfung übersehen werden könnten.

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

Beginnen Sie mit einer einzelnen openapi.yaml. Sie ist am einfachsten zu überprüfen und zu versionieren. Wenn die Datei groß wird oder Sie mehrere Hauptversionen parallel pflegen, teilen Sie sie nach Hauptversion (api-v1.yaml, api-v2.yaml) auf oder verwenden Sie $ref, um Schemas in separate Dateien aufzuteilen. Teilen Sie nicht zu früh; eine lesbare Datei ist besser als fünf fragmentierte.

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

Ja. Der Spec-First-Modus von Apidog ermöglicht es Ihnen, die Spezifikation in einem visuellen Editor zu bearbeiten und die Änderungen bidirektional mit Git zu synchronisieren. Er schreibt konsistentes YAML, sodass Ihre Diffs sauber und Ihre Pull Requests lesbar bleiben, während Sie dennoch die vollständige Git-Historie und -Überprüfung erhalten.

App herunterladen