Git-Native API Workflow: Definition & Erstellung

Ihr Code liegt in Git. Ihre CI-Pipelines, Reviews und Release-Historie liegen in Git. Ihre API-Spezifikation sollte denselben Workflow verwenden.

Apidog noch heute ausprobieren

Ein Git-nativer API-Workflow hält Ihre OpenAPI-Definition dort, wo auch Ihr Code liegt: im Repository. Sie bearbeiten die Spezifikation als YAML- oder JSON-Datei, committen Änderungen und lassen sie durch denselben Review-Prozess laufen wie jede andere Änderung. Keine separate Cloud-Datenbank. Kein Export-Import-Zyklus. Die Spezifikation ist eine Datei in Ihrem Repo.

💡 Apidog unterstützt dies direkt mit dem Spec-First-Modus. Sie entwerfen Ihre API in einem IDE-ähnlichen Editor und synchronisieren die Rohdateien bidirektional mit GitHub oder GitLab. Dieser Leitfaden zeigt, was ein Git-nativer API-Workflow bedeutet, wo Cloud-gebundene Spezifikationen Reibung erzeugen und wie Sie den Spec-First-Modus einrichten.

Was ein Git-nativer API-Workflow bedeutet

Ein Git-nativer API-Workflow behandelt Ihre API-Spezifikation als Code. Die OpenAPI-Datei liegt im Repository neben Ihren Services. Jede Änderung ist ein Commit. Jeder Commit hat Autor, Nachricht und Diff.

Das bringt Ihnen dieselben Eigenschaften, die Sie vom Quellcode erwarten:

• Versionshistorie: Sie sehen, wer welchen Endpunkt wann geändert hat. git blame funktioniert auch für Ihre Spezifikation.
• Branching und Review: Spezifikationsänderungen laufen über Pull Requests. Reviewer sehen den Diff, bevor etwas gemergt wird.
• Eine Quelle der Wahrheit: Die Datei in main ist der Vertrag. Dokumentation, Mocks, Tests und Generatoren lesen daraus.

Das ist die Kernidee eines Spec-First API-Workflows: Die Spezifikation führt, die Implementierung folgt. Mehr dazu finden Sie im Leitfaden zur Spec-First API-Entwicklung.

Der gegenteilige Ansatz speichert Ihre Spezifikation in einer proprietären Cloud-Anwendung. Das funktioniert oft am Anfang, erzeugt aber Reibung, sobald Teams, Reviews und Automatisierung wichtiger werden.

Das Problem mit Cloud-gebundenen API-Spezifikationen

Viele API-Design-Tools speichern die Spezifikation in ihrer eigenen Datenbank. Sie bearbeiten sie über eine UI. Die Datei, die Sie zu besitzen glauben, ist dann nicht wirklich Teil Ihres Repositories.

Typische Probleme:

• Reviews passieren an zwei Orten: Codeänderungen laufen über GitHub oder GitLab. Spezifikationsänderungen laufen über ein separates Tool mit eigener Historie und eigenen Kommentaren.
• Der Diff ist schwer sichtbar: Im Pull Request sehen Sie keinen sauberen Zeilen-für-Zeilen-Diff der OpenAPI-Datei.
• Export wird Pflichtarbeit: Für CI müssen Sie die Spezifikation exportieren, committen und hoffen, dass niemand parallel die Cloud-Version geändert hat.
• Automatisierung wird komplizierter: Linters, Vertragstests und Code-Generatoren erwarten eine Datei auf der Festplatte. Eine Cloud-Spezifikation erfordert vorher einen zusätzlichen Abrufschritt.

Wenn Sie Ihre API-Spezifikation als Code behandeln, entfällt diese Trennung. Die Datei ist die Spezifikation. Git ist die Historie. Ihre Pipeline erledigt den Rest. Das Prinzip wird ausführlicher in API-Spezifikation als Code erklärt.

Wie der Apidog Spec-First-Modus funktioniert

Der Spec-First-Modus richtet sich an Teams, die bereits mit Commits, Branches und Pull Requests arbeiten. Sie bearbeiten OpenAPI als YAML- oder JSON-Datei, und Apidog synchronisiert diese Dateien bidirektional mit Ihrem Git-Repository.

1. OpenAPI im IDE-ähnlichen Editor schreiben

Sie bearbeiten die Spezifikation in einem Code-Editor statt in einem Formular. Der Editor unterstützt:

• Syntax-Highlighting für YAML und JSON
• Validierung gegen OpenAPI- und Swagger-Schemas
• Auto-Vervollständigung für OpenAPI-Keywords, Typen und Referenzen

Sie behalten die Kontrolle über die konkrete Datei. Es gibt keine versteckten Felder und keine UI-spezifischen Metadaten.

2. Rohe YAML/JSON-Dateien versionieren

Die Spezifikation ist eine echte Datei. Beispiel:

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
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

Diese Datei landet im Repository. Was Sie bearbeiten, wird committet.

3. Durch die automatisch geparste Gliederung navigieren

Während Sie schreiben, parst Apidog die Datei und erstellt links eine visuelle Gliederung. Pfade, Operationen und Schemas erscheinen als klickbarer Baum.

Das ist besonders hilfreich bei großen Spezifikationen: Sie springen direkt zu einem Endpunkt oder Schema, statt durch Hunderte Zeilen YAML zu scrollen.

4. Bidirektional mit Git synchronisieren

Der Spec-First-Modus verbindet sich mit Ihrem Git-Provider und synchronisiert Änderungen in beide Richtungen.

Unterstützt werden:

• GitHub
• GitLab
• Azure DevOps über eine Git-Verbindung

Der Ablauf ist einfach:

1. Änderungen aus dem Remote-Branch ziehen.
2. Spezifikation im Apidog-Editor bearbeiten.
3. Änderungen committen.
4. Commit zurück in denselben Branch pushen.

So bleiben Repository und Apidog-Arbeitsbereich synchron.

5. Commit, Push und Synchronisierungsstatus prüfen

Sie müssen Apidog nicht verlassen, um Git-Änderungen zu verwalten. Sie können Änderungen stagen, eine Commit-Nachricht schreiben und pushen.

Ein Status-Indikator zeigt den Synchronisierungszustand. Nach einem erfolgreichen Push steht dort etwa „Gerade synchronisiert“. Wenn Sie vor dem Push Ihre Meinung ändern, können Sie nicht gepushte Änderungen verwerfen und zum letzten synchronisierten Zustand zurückkehren.

Für die GitHub-Seite des Workflows lesen Sie auch: OpenAPI-Spezifikation mit GitHub synchronisieren.

Einrichtungs-Walkthrough

So richten Sie ein synchronisiertes Spec-First-Projekt ein. Die vollständige Referenz finden Sie in den Spec-First-Modus-Dokumenten.

Schritt 1: Projekt aus einem Repository erstellen

Starten Sie in Apidog ein neues Spec-First-Projekt und verbinden Sie Ihren Git-Provider. Wählen Sie das Repository aus, das Ihre API-Spezifikation enthält, und wählen Sie den Branch, den Apidog verfolgen soll, typischerweise main.

Apidog zieht die vorhandenen Spezifikationsdateien in den Editor.

Schritt 2: OpenAPI-Datei bearbeiten

Öffnen Sie die OpenAPI-Datei im Editor. Nehmen Sie eine konkrete Änderung vor, zum Beispiel:

• neuen Endpunkt hinzufügen
• Schema anpassen
• Response ergänzen
• Beschreibung korrigieren
• Fehlerstatus wie 404 oder 409 dokumentieren

Syntax-Highlighting, Validierung und Auto-Vervollständigung helfen beim Schreiben. Die Gliederung links aktualisiert sich automatisch, sobald Sie die Datei ändern.

Schritt 3: Geänderte Dateien prüfen

Apidog zeigt an, welche Dateien seit der letzten Synchronisierung geändert wurden. Geänderte, hinzugefügte und gelöschte Dateien werden markiert.

So sehen Sie vor dem Commit genau, was aufgenommen wird.

Schritt 4: Commit-Nachricht schreiben

Schreiben Sie eine konkrete Commit-Nachricht wie in jedem Git-Client.

Gute Beispiele:

Add 404 response to getOrder

Update Order status enum

Add pagination parameters to listOrders

Vermeiden Sie unklare Nachrichten wie:

Update spec

Schritt 5: Pushen

Pushen Sie den Commit in den verfolgten Branch. Danach sehen Ihre Teamkollegen und Ihre CI-Pipeline die neue Version.

Schritt 6: Synchronisierungsstatus verifizieren

Prüfen Sie den Status-Indikator. Wenn dort „Gerade synchronisiert“ steht, stimmen Ihre lokalen Bearbeitungen und der Remote-Branch überein.

Der vollständige Zyklus lautet:

Pull → Bearbeiten → Commit → Push → Verifizieren

Kein Export. Keine zweite Wahrheitsquelle.

Spec-First- vs. Design-First-Modus

Apidog unterstützt zwei Arbeitsweisen. Der wichtigste Unterschied: Wo liegt die Spezifikation, und wie wird sie bearbeitet?

Bereich	Spec-First-Modus (Beta)	Design-First-Modus
Spezifikationsspeicher	Rohe YAML/JSON-Dateien in Git	Apidog Cloud-Projekt
Primärer Editor	IDE-ähnlicher Code-Editor	Visuelle formularbasierte Benutzeroberfläche
Versionskontrolle	Natives Git mit Commits, Branches und Diffs	Apidog-Historie und Branches
Bidirektionale Git-Synchronisierung	Ja: GitHub, GitLab, Azure DevOps	Über Export/Import
Am besten geeignet für	Teams, die in Git arbeiten	Teams, die einen visuellen Workflow bevorzugen

Keiner der Modi ist grundsätzlich besser. Sie passen zu unterschiedlichen Arbeitsweisen.

Nutzen Sie den Spec-First-Modus, wenn Ihr Review- und Release-Prozess bereits in Git läuft. Nutzen Sie den Design-First-Modus, wenn Ihr Team lieber visuell arbeitet und selten rohe OpenAPI-Dateien bearbeitet.

Wann sollten Sie den Spec-First-Modus verwenden?

Verwenden Sie den Spec-First-Modus, wenn:

• Ihre Spezifikation durch Pull Requests und Code-Reviews laufen soll.
• Sie git blame und echte Commit-Historie für Ihren API-Vertrag benötigen.
• Ihre CI-Pipeline Spezifikations-Linting, Vertragstests oder Code-Generierung ausführt.
• Mehrere Entwickler dieselbe Spezifikation bearbeiten.
• Sie saubere, zusammenführbare Diffs wollen.
• Sie Export- und Import-Schritte vermeiden möchten.

Bleiben Sie bei einem visuellen Cloud-First-Ansatz, wenn Ihr Team APIs entwirft, ohne rohe OpenAPI-Dateien zu schreiben, oder wenn Nicht-Entwickler die Spezifikation besitzen und einen formularbasierten Editor bevorzugen.

FAQ

Was ist ein Git-nativer API-Workflow?

Ein Git-nativer API-Workflow speichert Ihre OpenAPI-Spezifikation als Datei in einem Git-Repository. Änderungen laufen über Commits, Branches und Pull Requests. Dadurch folgt die Spezifikation demselben Review- und Versionskontrollprozess wie Ihr Anwendungscode.

Unterstützt der Apidog Spec-First-Modus GitHub und GitLab?

Ja. Der Spec-First-Modus synchronisiert bidirektional mit GitHub und GitLab. Azure DevOps wird über eine Git-Verbindung unterstützt. Sie verbinden das Repository, wählen einen Branch, und Apidog hält lokale Bearbeitungen und Remote-Zustand synchron.

Kann ich OpenAPI-Dateien als rohes YAML oder JSON bearbeiten?

Ja. Der Spec-First-Modus bietet einen IDE-ähnlichen Editor für rohes YAML und JSON. Er unterstützt Syntax-Highlighting, Schema-Validierung und Auto-Vervollständigung für OpenAPI und Swagger. Zusätzlich parst Apidog die Datei und zeigt eine navigierbare Gliederung in der linken Seitenleiste.

Was ist der Unterschied zwischen Spec-First- und Design-First-Modus?

Der Spec-First-Modus speichert die Spezifikation als Dateien in Git und bearbeitet sie in einem Code-Editor mit bidirektionaler Git-Synchronisierung. Der Design-First-Modus speichert die Spezifikation in einem Apidog-Cloud-Projekt und nutzt einen visuellen, formularbasierten Editor.

Wählen Sie Spec-First, wenn Ihr Workflow bereits auf Git basiert.

Fazit

Ein Git-nativer API-Workflow beendet die Trennung zwischen Code und API-Vertrag. Die Spezifikation wird zu einer Datei, die Datei zu einem Commit, und der Commit durchläuft den Review-Prozess, den Ihr Team bereits nutzt.

Der Apidog Spec-First-Modus kombiniert einen IDE-ähnlichen OpenAPI-Editor, eine navigierbare Gliederung und bidirektionale Git-Synchronisierung. Sie bearbeiten rohes YAML oder JSON, committen eine klare Nachricht, pushen und verifizieren den Status.

Probieren Sie den Spec-First-Modus aus und bringen Sie Ihre API-Spezifikation zurück nach Git.