OpenAPI Spezifikation mit GitHub synchronisieren: 2 einfache Methoden

Wenn Ihr OpenAPI-Dokument in einem Git-Repository liegt, Sie es aber in einem API-Client bearbeiten, entsteht schnell Reibung: YAML kopieren, wieder einfügen, Konflikte übersehen und hoffen, dass beim Import keine Felder verschwinden. Manuelle Synchronisierung zwischen Spec und Repo ist fehleranfällig — besonders dann, wenn mehrere Personen gleichzeitig daran arbeiten.

Apidog heute ausprobieren

Diese Anleitung zeigt, wie Sie Ihre OpenAPI-Spezifikation mit dem Spec-First-Modus von Apidog mit GitHub synchronisieren. Ziel: Die Spezifikation im Repository und die Spezifikation im Editor bleiben dieselbe Datei — nicht zwei Kopien, die Sie manuell abgleichen müssen. Sie verbinden einen Git-Anbieter, öffnen ein Projekt direkt aus einem Repository, bearbeiten die YAML und pushen die Änderung zurück zu GitHub. Die gleichen Schritte funktionieren auch mit GitLab.

Was bidirektionale Synchronisierung bedeutet

Bidirektionale Synchronisierung heißt: Änderungen laufen in beide Richtungen, ohne manuellen Export oder Import.

• Apidog → Git: Sie bearbeiten das OpenAPI-Dokument in Apidog, committen die Änderung und pushen sie als normalen Git-Commit auf den gewählten Branch.
• Git → Apidog: Wenn jemand eine Änderung auf denselben Branch pusht, zieht Apidog diese Änderung zurück in den Editor.

Das Repository bleibt die Source of Truth. Apidog ist der Editor darüber. Genau darum geht es bei einem Git-nativen API-Workflow: Die API-Spezifikation wird versioniert, reviewed und historisch nachvollziehbar wie jede andere Datei in Ihrer Codebasis.

Voraussetzungen

Sie benötigen:

• Apidog, angemeldet in Desktop-App oder Web-App.
• Ein GitHub- oder GitLab-Repository mit OpenAPI-Dokument oder Schreibzugriff auf ein entsprechendes Repository.
• Aktivierten Spec-First-Modus (Beta).
• Schreibrechte für den Branch, den Sie synchronisieren möchten.

Nur-Lese-Zugriff reicht zum Pull, aber nicht zum Push. Azure DevOps wird ebenfalls über Git Connection unterstützt.

Schritt 1: Git-Anbieter verbinden

Autorisieren Sie Apidog zuerst für Ihren Git-Anbieter.

1. Öffnen Sie Apidog.
2. Erstellen Sie ein neues Projekt.
3. Wählen Sie den Spec-First-Modus.
4. Wählen Sie als Quelle GitHub oder GitLab.
5. Klicken Sie auf Autorisieren.
6. Erteilen Sie Zugriff auf die Repositories, die Sie synchronisieren möchten.

Auf GitHub können Sie den Zugriff auf bestimmte Repositories begrenzen, statt Zugriff auf das gesamte Konto zu geben.

Nach der Autorisierung werden Sie zurück zu Apidog geleitet. Die Verbindung müssen Sie nur einmal pro Anbieter einrichten; weitere Projekte können sie wiederverwenden.

Die vollständige Referenz, inklusive Azure DevOps über Git Connection, finden Sie in der Dokumentation zum Spec-First-Modus.

Schritt 2: Projekt aus Repository und Branch erstellen

Jetzt zeigen Sie Apidog, wo die OpenAPI-Datei liegt.

1. Wählen Sie den verbundenen Git-Anbieter aus.
2. Wählen Sie das Repository mit Ihrer OpenAPI-Spezifikation.
3. Wählen Sie den Branch, mit dem synchronisiert werden soll, zum Beispiel main.
4. Bestätigen Sie den Pfad zur OpenAPI-Datei, falls Apidog danach fragt, zum Beispiel:
   • openapi.yaml
   • docs/openapi.yaml
   • api/openapi.yml
5. Erstellen Sie das Projekt.

Apidog lädt die Spezifikation vom gewählten Branch und öffnet sie. Die linke Seitenleiste wird aus dem OpenAPI-Dokument aufgebaut: Endpunkte, Schemas und weitere Bestandteile erscheinen als navigierbare Struktur.

Schritt 3: OpenAPI-YAML bearbeiten

Im Spec-First-Modus bearbeiten Sie die rohe OpenAPI-YAML direkt. Apidog bietet dabei Syntax-Hervorhebung, Inline-Validierung und Autovervollständigung. Die visuelle Gliederung bleibt während der Bearbeitung synchron.

Beispiel: Ein einfacher Health-Check-Endpunkt.

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

Während der Bearbeitung passieren zwei Dinge:

• Die linke Seitenleiste aktualisiert sich automatisch und zeigt /health als neue Operation.
• Der Validator markiert Probleme direkt im Editor, etwa fehlende responses, fehlerhafte $ref-Verweise oder YAML-Einrückungsfehler.

So sehen Sie Fehler vor dem Commit statt erst später in CI/CD oder beim Generieren von Dokumentation, Mocks oder Tests.

Wenn Sie tiefer in Diffs, Historie und API-Spec-Versionierung einsteigen möchten, lesen Sie den Leitfaden zur OpenAPI-Versionskontrolle mit Git.

Schritt 4: Committen und pushen

Wenn die Änderung korrekt aussieht, pushen Sie sie zurück zu GitHub.

1. Öffnen Sie das Commit-Panel bzw. den Git-/Source-Control-Bereich des Projekts.
2. Prüfen Sie die Änderung im Diff.
3. Schreiben Sie eine Commit-Nachricht, zum Beispiel:

Add /health endpoint

1. Klicken Sie auf Committen & Pushen.

Apidog erstellt einen Commit auf dem gewählten Branch und pusht ihn ins Remote-Repository. Wenn Sie das Repository auf GitHub öffnen, sehen Sie den Commit in der Branch-Historie.

Wenn Sie eine Änderung vor dem Push verwerfen möchten, können Sie nicht gepushte Bearbeitungen zurücksetzen. Bis zum Commit bleiben Ihre Experimente lokal.

Schritt 5: Synchronisierungsstatus prüfen

Apidog zeigt den aktuellen Sync-Status an.

Nach einem erfolgreichen Push steht der Status auf „Gerade synchronisiert“. Das bedeutet: Editor und Remote-Branch enthalten dieselbe Version der OpenAPI-Datei.

Mit der Zeit ändert sich die Anzeige, zum Beispiel zu „Vor 5 Minuten synchronisiert“. Wenn jemand anderes auf den Branch pusht, zieht Apidog die Änderung und aktualisiert den Status nach dem Abgleich.

Wenn der Status ausstehende oder veraltete Änderungen anzeigt, sind lokale Kopie und Remote-Repository auseinander gelaufen. In diesem Fall sollten Sie zuerst pullen oder Konflikte auflösen, bevor Sie weiterarbeiten.

Fehlerbehebung

Autorisierung abgelaufen oder widerrufen

Wenn Push-Vorgänge mit Berechtigungsfehlern fehlschlagen, autorisieren Sie den Git-Anbieter erneut. Tokens können ablaufen oder auf Anbieterseite widerrufen werden.

Falscher Branch

Wenn Sie auf einen geschützten main-Branch pushen, der Pull Requests verlangt, wird der Push abgelehnt.

Optionen:

• Einen anderen Branch für die Synchronisierung verwenden.
• Branch-Schutzregeln anpassen.
• Prüfen, ob der in Apidog gewählte Branch der Branch ist, auf dem Sie Commits erwarten.

Merge-Konflikte

Wenn jemand anderes denselben Branch geändert hat, während Sie lokal bearbeitet haben, ist das Remote-Repository weiter als Ihre lokale Kopie.

Vorgehen:

1. Neueste Änderungen pullen.
2. YAML-Konflikte auflösen.
3. Datei validieren.
4. Erneut committen und pushen.

Da die OpenAPI-Spezifikation reiner Text ist, lösen Sie Konflikte wie bei jeder anderen Code-Datei.

Validierungsfehler

Apidog kann ungültige YAML anzeigen und markieren. Beheben Sie die markierten Fehler möglichst vor dem Commit. Eine valide Spezifikation hält generierte Dokumentation, Mocks und Tests konsistent.

FAQ

Funktioniert das auch mit GitLab und Azure DevOps?

Ja. Der Spec-First-Modus unterstützt GitHub und GitLab direkt sowie Azure DevOps über Git Connection. Der Ablauf bleibt gleich:

1. Anbieter verbinden.
2. Repository und Branch auswählen.
3. OpenAPI-Datei bearbeiten.
4. Committen und pushen.

Nur der Autorisierungsbildschirm unterscheidet sich je nach Anbieter.

Was passiert, wenn ein Teamkollege die Spezifikation im Repository bearbeitet?

Apidog zieht die Änderung im Rahmen der bidirektionalen Synchronisierung zurück in den Editor.

Wenn die Änderungen unterschiedliche Bereiche der Datei betreffen, können sie sauber zusammengeführt werden. Wenn sie sich überschneiden, lösen Sie einen normalen Git-Konflikt.

Kann ich eine Änderung rückgängig machen, bevor sie GitHub erreicht?

Ja. Bis Sie auf Committen & Pushen klicken, bleiben Ihre Änderungen lokal. Verwenden Sie Nicht gepushte Bearbeitungen verwerfen, um das Dokument auf den letzten synchronisierten Zustand zurückzusetzen.