API Spezifikation als Code behandeln: Was bedeutet das?

Ihr API-Vertrag liegt wahrscheinlich an drei Orten gleichzeitig: als Diagramm im Wiki, als exportierte Postman-Collection und als Markdown-Datei, die seit zwei Releases nicht mehr zur laufenden API passt. Wenn diese Quellen voneinander abweichen, integriert Ihr Team gegen Annahmen statt gegen einen Vertrag.

Apidog noch heute ausprobieren

Behandeln Sie Ihre API-Spezifikation deshalb wie Code: Schreiben Sie eine OpenAPI-Datei, committen Sie sie in Git und prüfen Sie Änderungen per Pull Request. Aus dieser Datei generieren Sie Mocks, Tests, Dokumentation und SDKs. Die Spezifikation wird damit zur einzigen Quelle der Wahrheit.

Dieser Leitfaden zeigt, wie Spec-as-Code funktioniert, wie Sie OpenAPI als Artefakt im Repository verwalten und wie Sie daraus einen praktischen Workflow für Entwicklung, Review und CI bauen.

Was Spec-as-Code bedeutet

Spec-as-Code bedeutet: Ihre API-Definition ist eine reine Textdatei in der Versionskontrolle. Kein isoliertes Dokument. Kein Tool-Export. Keine Datei, die nur lokal auf einem Rechner liegt.

Sie können die Spezifikation wie jede andere Quelldatei behandeln:

git diff api/openapi.yaml
git checkout -b change-order-status
git commit -m "Add delivered status to Order"
git push

Die Idee kommt aus Docs-as-Code: Dokumentation liegt im selben Repository wie der Code und läuft durch dieselbe Pipeline. Spec-as-Code wendet diese Disziplin auf den API-Vertrag selbst an.

Das OpenAPI-Dokument in YAML oder JSON ist das zentrale Artefakt. Alles andere wird daraus abgeleitet:

• Mock-Server
• Vertragstests
• Referenzdokumentation
• SDKs
• Client-Typen
• Validierungsregeln

Wenn ein Entwickler wissen möchte, was GET /users/{id} zurückgibt, liest er die Spezifikation. Wenn QA Tests schreibt, prüft sie gegen dieselbe Spezifikation. Wenn Partner integrieren, verwenden sie ein daraus generiertes SDK.

Eine Datei. Viele Ausgaben.

Warum Sie die Spezifikation wie Code behandeln sollten

Sobald die Spezifikation in Git liegt, können Sie Ihre bestehenden Engineering-Workflows darauf anwenden.

1. Änderungen per Pull Request prüfen

Eine Endpoint-Änderung wird als Diff sichtbar:

 status:
   type: string
-  enum: [pending, shipped]
+  enum: [pending, shipped, delivered]

Reviewer sehen sofort:

• welche Felder hinzugefügt wurden
• welche Statuscodes geändert wurden
• ob eine Antwortstruktur inkompatibel wird
• ob ein Endpoint entfernt oder umbenannt wurde

Breaking Changes tauchen dadurch nicht erst in Produktion auf, sondern im PR-Review. Das ist der Kern eines Git-nativen API-Workflows.

2. Saubere Diffs erhalten

YAML ist gut diffbar. Eine kleine Änderung bleibt eine kleine Änderung. Das ist deutlich einfacher zu prüfen als ein Binär-Export oder ein gehostetes Dokument, bei dem unklar ist, was sich tatsächlich geändert hat.

Mit einer Spezifikation in Git funktionieren Standardwerkzeuge direkt:

git blame api/openapi.yaml
git log -- api/openapi.yaml
git show HEAD~1:api/openapi.yaml

3. Versionierung nachvollziehbar machen

Jede Änderung hat:

• Commit
• Autor
• Zeitstempel
• Review-Kontext
• optional ein Release-Tag

Sie können Releases markieren:

git tag api-v1.2.0
git push origin api-v1.2.0

Sie können für ein Redesign verzweigen:

git checkout -b api-v2

Und Sie können fehlerhafte Änderungen zurückrollen:

git revert <commit-sha>

Für Strategien rund um Tags, Branches und API-Versionen siehe OpenAPI-Versionskontrolle mit Git.

4. Eine einzige Quelle der Wahrheit erzwingen

Wenn Mocks, Tests und Dokumentation aus derselben Datei entstehen, können sie nicht unabhängig voneinander abweichen.

Der Workflow wird einfach:

1. OpenAPI-Datei ändern
2. PR öffnen
3. Spezifikation linten
4. Mocks/Dokumentation/Tests neu generieren
5. Merge nach Review

Anliegen	Spezifikation in einem gehosteten Tool	API-Spezifikation als Code
Änderungsüberprüfung	Manuell, leicht zu übersehen	PR-Diff, blockierende Überprüfung
Historie	Begrenzt oder anbietergebunden	Vollständiges Git-Protokoll
Rollback	Oft manuell	git revert
Quelle der Wahrheit	Zweideutig	Die committete Datei
CI-Integration	Aufgesetzt	Nativ

OpenAPI als Artefakt im Repository

OpenAPI ist das naheliegende Format für Spec-as-Code, weil es maschinenlesbar, weit verbreitet und von vielen Tools unterstützt wird.

Ein typischer Speicherort:

your-service/
├── src/
├── tests/
├── api/
│   └── openapi.yaml
└── package.json

Ein kleiner OpenAPI-3.1-Ausschnitt:

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.

Wenn Sie ein Feld zu Order hinzufügen, sieht der PR-Diff genau diese Änderung. Wenn Sie das status-Enum ändern, ist das sofort reviewbar. Wenn Sie einen Statuscode entfernen, kann CI den Merge blockieren.

Spezifikation in CI prüfen

Ein Spec-as-Code-Workflow sollte mindestens einen CI-Check enthalten. Der erste sinnvolle Schritt ist Linting.

Beispiel mit einer generischen CI-Struktur:

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "api/openapi.yaml"

jobs:
  validate-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI file
        run: |
          npx @redocly/cli lint api/openapi.yaml

Damit verhindern Sie, dass ungültige OpenAPI-Dateien gemergt werden.

Typische Regeln, die Sie prüfen sollten:

• jeder Endpoint hat eine operationId
• jeder Response-Code hat eine Beschreibung
• Schemas verwenden konsistente Typen
• Breaking Changes werden markiert oder blockiert
• interne Endpoints werden nicht versehentlich veröffentlicht

Was Sie aus der Spezifikation generieren können

Der Hauptnutzen entsteht nicht dadurch, dass die Datei existiert. Der Nutzen entsteht dadurch, dass Sie die Datei in ausführbare Artefakte verwandeln.

Mocks

Ein Mock-Server ermöglicht Integration, bevor die Implementierung fertig ist.

Workflow:

1. Endpoint in openapi.yaml definieren
2. Mock aus der Spezifikation starten
3. Frontend oder Mobile-App gegen den Mock entwickeln
4. Implementierung später gegen dieselbe Spezifikation bauen

Das reduziert Blocker zwischen Teams. Frontend-Teams müssen nicht warten, bis Backend-Endpunkte deployed sind.

Vertragstests

Vertragstests prüfen, ob die laufende API zur Spezifikation passt.

Sie erkennen zum Beispiel:

• ein dokumentiertes Feld fehlt in der Response
• ein nicht dokumentiertes Feld wird zurückgegeben
• ein Statuscode ist nicht spezifiziert
• ein Datentyp stimmt nicht
• ein Pflichtfeld ist nullable, obwohl es das nicht sein sollte

Der wichtige Punkt: Die Spezifikation wird nicht nur gelesen, sondern durchgesetzt.

Dokumentation

Referenzdokumentation sollte aus der Spezifikation gerendert werden. Schreiben Sie Endpoint-Tabellen nicht manuell, wenn OpenAPI sie bereits enthält.

Dadurch bleiben diese Informationen konsistent:

• Pfade
• Methoden
• Query-Parameter
• Request-Bodies
• Response-Schemas
• Statuscodes
• Authentifizierung

SDKs

Aus derselben Spezifikation können Client-Bibliotheken oder Typdefinitionen generiert werden. Das ist besonders hilfreich für Partner, interne Plattformteams oder mehrere Frontends.

Die Regel bleibt immer gleich:

OpenAPI-Spezifikation rein
→ Mocks, Tests, Dokumentation und SDKs raus

Wie Apidog die Spezifikation zur Quelle der Wahrheit macht

Spec-as-Code manuell aufzubauen bedeutet oft, mehrere Werkzeuge zu verbinden:

• Editor
• OpenAPI-Linter
• Mock-Server
• Dokumentationsgenerator
• Test-Runner
• Git-Hooks
• CI-Jobs

Apidog bündelt diese Schritte in einem Workflow.

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

Der praktische Teil ist die bidirektionale Git-Synchronisation. Apidog kann Ihre OpenAPI-Datei aus einem Repository lesen und Änderungen zurückschreiben. Dadurch bleiben die Datei in Git und das Projekt in Apidog konsistent.

Das erlaubt zwei Arbeitsweisen im selben Team:

• visuell entwerfen, wenn das schneller ist
• YAML direkt bearbeiten, wenn das präziser ist

Beide Wege landen wieder in derselben committeten Datei. Ihr PR-Review-Workflow bleibt erhalten, während das Team trotzdem einen visuellen Editor nutzen kann.

Für die konkrete Einrichtung siehe wie Sie Ihre OpenAPI-Spezifikation mit GitHub synchronisieren.

Das Ziel bleibt: Die OpenAPI-Datei ist die Quelle der Wahrheit. Visuelle Tools liegen darüber, ersetzen sie aber nicht.

Häufige Fallstricke

1. Spezifikation und Implementierung driften auseinander

Eine Spezifikation allein verhindert keine Abweichung. Wenn niemand prüft, ob der laufende Dienst zur Datei passt, entsteht wieder Drift.

Lösung:

• Vertragstests in CI ausführen
• Tests gegen die committete Spezifikation laufen lassen
• Build bei Nichtübereinstimmung fehlschlagen lassen

2. Generierten und handgeschriebenen Code vermischen

Entscheiden Sie früh, welche Richtung maßgeblich ist:

• Spec-first: OpenAPI ist die Quelle, Code wird dagegen geprüft
• Code-first: OpenAPI wird aus Code-Annotationen generiert

Beides gleichzeitig führt schnell zu Unsicherheit. Wenn niemand weiß, welche Datei die Wahrheit ist, ist Spec-as-Code wirkungslos.

3. Die Spezifikation nur als Dokumentation behandeln

Eine Spezifikation, die nur gelesen wird, ist ein Dokument.

Eine Spezifikation, aus der Sie Mocks, Tests und SDKs generieren, ist ein Vertrag.

Der Wert entsteht durch Automatisierung:

Spec ändern
→ PR prüfen
→ CI validiert
→ Artefakte aktualisieren
→ Implementierung wird getestet

4. Review überspringen

Eine OpenAPI-Datei in Git ohne Review ist nur eine Datei in Git.

Machen Sie Reviews verpflichtend:

• Code Owner für api/openapi.yaml
• mindestens ein Review für API-Änderungen
• CI-Checks als Merge-Voraussetzung
• Breaking-Change-Regeln definieren

Erste Schritte

Sie müssen nicht alles auf einmal umbauen. Starten Sie inkrementell.

Schritt 1: Spezifikation committen

Legen Sie die OpenAPI-Datei an einem festen Pfad ab:

api/openapi.yaml

Committen Sie sie zusammen mit dem Service-Code.

Schritt 2: PR-Review erzwingen

Behandeln Sie Änderungen an der Spezifikation wie Codeänderungen.

Beispiel für eine einfache Review-Regel:

Änderungen unter api/openapi.yaml benötigen Review durch das API-Team.

Schritt 3: Eine Ausgabe generieren

Starten Sie mit einem Artefakt:

• Mock-Server
• Referenzdokumentation
• SDK
• Typdefinitionen

Wichtig ist, dass die Ausgabe aus der Spezifikation entsteht und nicht separat gepflegt wird.

Schritt 4: CI-Validierung hinzufügen

Führen Sie mindestens OpenAPI-Linting bei jedem Pull Request aus.

Optional später ergänzen:

• Breaking-Change-Erkennung
• Schema-Validierung
• Security-Regeln
• Dokumentations-Build

Schritt 5: Vertragstests ergänzen

Sobald die Spezifikation stabil im Workflow ist, prüfen Sie die laufende API gegen sie.

Damit schließen Sie den Kreis:

Spezifikation beschreibt Vertrag
Implementierung erfüllt Vertrag
CI erzwingt Vertrag

Fazit

Spec-as-Code macht Ihren API-Vertrag reviewbar, versionierbar und automatisierbar. Die OpenAPI-Datei liegt in Git, Änderungen laufen durch Pull Requests, und Mocks, Tests, Dokumentation sowie SDKs entstehen aus derselben Quelle.

Wenn Sie visuelle Bearbeitung und Git-Synchronisation kombinieren möchten, probieren Sie Apidogs Spec-First-Modus aus und lassen Sie die OpenAPI-Datei die einzige Quelle der Wahrheit bleiben.

FAQ

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

Sie folgen derselben Philosophie: Das Artefakt liegt in der Versionskontrolle und läuft durch die normale Pipeline.

Docs-as-Code wendet das auf Dokumentation an. Spec-as-Code wendet es auf den API-Vertrag selbst an. In der Praxis ergänzen sie sich, weil aus einer committeten Spezifikation generierte Dokumentation automatisch Docs-as-Code ist.

Welches Format sollte die Spezifikationsdatei verwenden?

OpenAPI in YAML ist die gängige Wahl. YAML ist menschenlesbar, gut diffbar und maschinell auswertbar. JSON funktioniert ebenfalls, erzeugt in Pull Requests aber oft weniger übersichtliche Diffs.

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

Fügen Sie Vertragstests zur CI hinzu. Diese Tests prüfen, ob der laufende Dienst der committeten Spezifikation entspricht.

Wenn ein Endpoint ein nicht deklariertes Feld zurückgibt, ein dokumentiertes Feld weglässt oder einen falschen Typ liefert, schlägt der Build fehl. Dadurch wird die Spezifikation von einem Dokument zu einem durchgesetzten Vertrag.