API Spezifikation als Code behandeln: Was bedeutet das?

Ihr API-Vertrag existiert wahrscheinlich an drei Orten gleichzeitig. Ein Diagramm in einem Wiki. Eine Postman-Sammlung, die jemand im letzten Quartal exportiert hat. Ein handschriftliches Markdown-Dokument, das zwei Releases zuvor vom laufenden Dienst abgewichen ist. Wenn diese drei nicht übereinstimmen, rät Ihr Team. Raten führt zu fehlerhaften Integrationen.

Die Behandlung Ihrer API-Spezifikation als Code behebt dies. Sie schreiben eine OpenAPI-Datei, committen sie in Git und überprüfen sie wie jede andere Quelldatei. Aus dieser einzelnen Datei generieren Sie Mocks, Tests, Dokumentation und SDKs. Die Spezifikation hört auf, ein nachträglicher Gedanke zu sein, und wird zum Vertrag, gegen den alle entwickeln.

Dieser Leitfaden erklärt, was Spec-as-Code bedeutet, warum die OpenAPI-Datei die gleiche Strenge wie Ihr Anwendungscode verdient und wie Sie den Workflow ausführen, ohne mit Ihren Tools zu kämpfen.

Was Spec-as-Code bedeutet

Spec-as-Code bedeutet, dass Ihre API-Definition eine reine Textdatei ist, die in der Versionskontrolle liegt. Kein Datenbankeintrag. Kein gehostetes Dokument mit einem Freigabelink. Eine Datei, die Sie git diffen, verzweigen und zusammenführen können.

Die Idee ist direkt von Docs-as-Code übernommen, wo die Dokumentation im selben Repository wie der Code liegt, den sie beschreibt, und über dieselbe Pipeline bereitgestellt wird. Spec-as-Code wendet dieselbe Disziplin auf den API-Vertrag selbst an. Das OpenAPI-Dokument (YAML oder JSON) ist das Artefakt. Alles andere, was davon abhängt, wird daraus generiert.

Diese Umstellung hat eine große Konsequenz. Die Spezifikation wird zur einzigen Quelle der Wahrheit. Wenn ein Entwickler wissen möchte, was /users/{id} zurückgibt, liest er die Spezifikation, nicht eine veraltete Wiki-Seite. Wenn die QA einen Test schreibt, prüft sie gegen die Spezifikation. Wenn ein Partner integriert, zieht er ein aus der Spezifikation generiertes SDK. Eine Datei, viele Ausgaben.

Warum die Spezifikation wie Code behandeln

Sobald die Spezifikation eine Datei in Git ist, erben Sie jeden Workflow, dem Sie bereits für Quellcode vertrauen.

Überprüfung in Pull Requests. Eine Änderung an einem Endpunkt erscheint als Diff in einem PR. Rezensenten sehen genau, welche Felder sich geändert haben, welche Statuscodes hinzugefügt wurden und ob eine Antwortstruktur die Abwärtskompatibilität verletzt hat. Eine Breaking Change ist in der Produktion keine Überraschung mehr. Es ist ein Kommentar-Thread vor dem Merge. Dies ist der Kern eines Git-nativen API-Workflows.

Diff-freundliches Format. Einfaches YAML lässt sich sauber diffen. Sie können eine Fünf-Zeilen-Änderung lesen und in Sekundenschnelle verstehen. Vergleichen Sie das mit einem Binär-Export oder einem gehosteten Tool, bei dem „was sich geändert hat“ unsichtbar ist. Mit der Spezifikation in Git funktionieren blame, history und diffs einfach.

Echte Versionierung. Jede Änderung hat einen Commit, einen Autor und einen Zeitstempel. Sie können eine Freigabe taggen, für ein v2-Redesign verzweigen und eine fehlerhafte Änderung mit einem Befehl rückgängig machen. Ihre API-Historie wird überprüfbar. Für einen tieferen Einblick in Tagging- und Branching-Strategien, siehe OpenAPI-Versionskontrolle mit Git.

Eine einzige Quelle der Wahrheit. Da Mocks, Tests und Dokumentation alle von derselben Datei abgeleitet sind, können sie nicht unabhängig voneinander abweichen. Aktualisieren Sie die Spezifikation, generieren Sie neu, und jede Ausgabe bleibt konsistent.

Hier ist, wie sich die beiden Ansätze in der Praxis vergleichen lassen.

OpenAPI als Artefakt

OpenAPI ist das offensichtliche Format für die Spezifikation, da es weit verbreitet und maschinenlesbar ist. Ein kleiner, aber vollständiger Ausschnitt einer OpenAPI 3.1-Datei, die Sie in Ihrem Repository aufbewahren würden.

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 format: uuid
 responses:
 "200":
 description: The requested order
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 required: [id, status, total]
 properties:
 id:
 type: string
 format: uuid
 status:
 type: string
 enum: [pending, shipped, delivered]
 total:
 type: number
 format: float

Diese Datei ist der Vertrag. Fügen Sie ein Feld zu Order hinzu, und der Diff ist eine Zeile. Ändern Sie das status-Enum, und ein Rezensent sieht es sofort. Bewahren Sie es unter api/openapi.yaml neben Ihrem Service-Code auf, und die Spezifikation reist mit der Implementierung, die sie beschreibt.

Spezifikation und Dokumentation

Der Vorteil einer einzigen Quelldatei ist alles, was Sie daraus generieren.

Mocks. Richten Sie einen Mock-Server auf die Spezifikation aus, und Sie erhalten eine ausführbare API, bevor ein einziger Endpunkt erstellt wird. Frontend- und mobile Teams beginnen am ersten Tag mit der Integration gegen den Vertrag. Wenn sich die Spezifikation ändert, ändert sich der Mock mit ihr.

Tests. Generieren Sie Vertragstests, die überprüfen, ob der Live-Dienst der Spezifikation entspricht. Wenn ein bereitgestellter Endpunkt ein Feld zurückgibt, das die Spezifikation nie deklariert hat, schlägt der Test fehl. Dies fängt Abweichungen zwischen dem Vertrag und dem laufenden Code ab, bevor Kunden dies bemerken.

Dokumentation. Rendern Sie die Spezifikation automatisch in Referenzdokumentation. Niemand schreibt mehr Endpunkt-Tabellen von Hand. Die Dokumentation stimmt mit der Spezifikation überein, weil sie die gerenderte Spezifikation ist.

SDKs. Generieren Sie Client-Bibliotheken in mehreren Sprachen aus derselben Datei. Partner erhalten ein typisiertes SDK, das immer den aktuellen Vertrag widerspiegelt.

Jede Ausgabe ist eine Funktion der Spezifikation. Ändern Sie die Eingabe, generieren Sie die Ausgaben neu, und Konsistenz ist kostenlos.

Wie Apidog die Spezifikation zur Quelle der Wahrheit macht

Spec-as-Code manuell auszuführen bedeutet, eine CLI, einen Mock-Server, einen Doku-Generator und einen Git-Hook zusammenzuflicken. Apidog fasst dies in einem Workflow zusammen.

Der Spec-First-Modus von Apidog behandelt Ihre OpenAPI-Datei als die maßgebliche Definition. Sie entwerfen Endpunkte gemäß der Spezifikation, und Apidog hält Ihre Mocks, Tests und Dokumentation synchron damit.

Das Element, das dies praktikabel macht, ist die bidirektionale Git-Synchronisation. Apidog kann Ihre OpenAPI-Datei aus einem Repository lesen und Änderungen zurückschreiben, sodass die Datei in Git und das Projekt in Apidog übereinstimmen. Entwerfen Sie visuell, wenn dies schneller ist, bearbeiten Sie YAML direkt, wenn dies schneller ist, und beide Wege landen in derselben committeten Datei. Das hält Ihren PR-Review-Workflow intakt und bietet Ihrem Team gleichzeitig einen umfangreicheren Editor. Für die Mechanik des Hochladens von Spezifikationsänderungen, siehe wie Sie Ihre OpenAPI-Spezifikation mit GitHub synchronisieren.

Das Ergebnis: Die OpenAPI-Datei bleibt die einzige Quelle der Wahrheit, und die visuellen Tools liegen darauf auf, anstatt sie zu ersetzen.

Häufige Fallstricke

Spec-as-Code ist unkompliziert, aber ein paar Fallstricke lauern für Teams am Anfang.

Abweichung zwischen Spezifikation und Implementierung. Das Schreiben der Spezifikation reicht nicht aus. Wenn nichts überprüft, ob der laufende Dienst damit übereinstimmt, driften die beiden leise auseinander. Fügen Sie Vertragstests zur CI hinzu, damit eine Nichtübereinstimmung den Build fehlschlagen lässt, nicht den Kunden.

Verwechslung von generiertem und handgeschriebenem Code. Entscheiden Sie, ob die Spezifikation aus Code-Annotationen generiert oder als Quelle handgeschrieben wird. Eine Vermischung beider führt zu einer Datei, bei der niemand weiß, welche Hälfte maßgeblich ist. Wählen Sie eine Richtung. Wenn die Spezifikation Ihre Quelle der Wahrheit ist, behandeln Sie Code-Annotationen als das, was Sie dagegen prüfen, nicht als eine zweite Masterkopie.

Die Spezifikation als Dokumentation behandeln, nicht als Vertrag. Eine Spezifikation, die Sie nur lesen, ist ein Dokument. Eine Spezifikation, aus der Sie Mocks, Tests und SDKs generieren, ist ein Vertrag. Der Wert kommt vom Verdrahten der Ausgaben, nicht vom bloßen Existieren der Datei.

Überprüfung überspringen. Eine Spezifikation in Git, die ohne Überprüfung zusammengeführt wird, ist nur eine Datei in Git. Der Punkt ist der Pull Request. Verlangen Sie eine Überprüfung bei Spezifikationsänderungen auf die gleiche Weise, wie Sie es für Code tun.

Erste Schritte

Sie können Spec-as-Code inkrementell einführen.

1. Committen Sie Ihre Spezifikation. Verschieben Sie Ihre OpenAPI-Datei in das Repository unter einem bekannten Pfad, wie api/openapi.yaml.
2. PR-Überprüfung erforderlich machen. Spezifikationsänderungen müssen dieselbe Überprüfung durchlaufen wie Code. Diffe werden zur Konversation.
3. Generieren Sie eine Ausgabe. Beginnen Sie mit Mocks oder Dokumentation. Verbinden Sie die Spezifikation mit einem Generator, damit die Ausgabe aktualisiert wird, wenn sich die Datei ändert.
4. Fügen Sie einen CI-Check hinzu. Linten Sie die Spezifikation bei jedem PR. Erkennen Sie ungültiges OpenAPI vor dem Merge.
5. Schließen Sie den Kreislauf mit Vertragstests. Sobald Mocks und Dokumentation fließen, fügen Sie Tests hinzu, die überprüfen, ob der Live-Dienst der Spezifikation entspricht.

Jeder Schritt steht für sich allein. Sie erhalten bereits im ersten Schritt Wert und steigern diesen mit jeder Ergänzung.

Die Umstellung ist leicht zu beschreiben und hat eine große Wirkung. Eine Datei in Git, wie Code überprüft, generiert alles, was davon abhängt. Wenn Sie die visuelle Bearbeitung und Git-Synchronisation integriert haben möchten, probieren Sie Apidogs Spec-First-Modus aus und lassen Sie die OpenAPI-Datei Ihre einzige Quelle der Wahrheit bleiben.

FAQ

Ist „API Spec as Code“ dasselbe wie „Docs as Code“?

Sie teilen dieselbe Philosophie: Das Artefakt in der Versionskontrolle halten und über Ihre normale Pipeline bereitstellen. Docs-as-Code wendet dies auf die Dokumentation an. Spec-as-Code wendet dies auf den API-Vertrag selbst an. In der Praxis verstärken sie sich gegenseitig, da aus einer committeten Spezifikation generierte Dokumente per Definition Docs-as-Code sind.

Welches Format sollte die Spezifikationsdatei verwenden?

OpenAPI in YAML ist die gängige Wahl. YAML lässt sich in Pull Requests sauber diffen und ist für Menschen lesbar, während es gleichzeitig maschinell analysierbar ist, um Mocks, Tests und SDKs zu generieren. JSON funktioniert auch, aber YAML neigt dazu, sauberere Diffe zu erzeugen.

Wie verhindere ich, dass die Spezifikation von der eigentlichen API abweicht?

Fügen Sie Vertragstests zur CI hinzu, die überprüfen, ob der laufende Dienst der committeten Spezifikation entspricht. Wenn ein Endpunkt ein nicht deklariertes Feld zurückgibt oder ein dokumentiertes weglässt, schlägt der Build fehl. Diese Rückkopplungsschleife macht die Spezifikation von einem hoffnungsvollen Dokument zu einem durchgesetzten Vertrag.