Wie verbindet man Apidog mit GitHub und GitLab

Wenn Ihre API-Spezifikationen in Apidog liegen, Ihre Quelle der Wahrheit aber in Git, möchten Sie, dass die beiden übereinstimmen. Die Apidog Git-Integration schließt diese Lücke. Sie ermöglicht es Ihnen, ein GitHub-, GitLab- oder Azure DevOps-Repository mit Ihrem Projekt zu verbinden, Ihre OpenAPI-Spezifikationen in die Versionskontrolle zu übertragen und Repository-Änderungen zurück in Apidog zu ziehen. Sie erhalten einen sauberen Audit-Trail, Code-Review bei Spezifikationsänderungen und ein Backup, das alles überlebt, was in der App passiert.

Dies ist die umfassende Referenz. Sie deckt jeden von Apidog unterstützten Anbieter ab, beide Kommunikationswege des Produkts mit Git und die praktischen Entscheidungen, vor denen Sie stehen werden: welches Repository, welcher Branch, wer pushen kann und was zu tun ist, wenn etwas schiefgeht. Wenn Sie nur die fokussierte GitHub-Anleitung benötigen, lesen Sie den speziellen Leitfaden zum Synchronisieren Ihrer OpenAPI-Spezifikation mit GitHub. Hier gehen wir ins Detail.

Was die Apidog Git-Integration leistet

Apidog kommuniziert auf zwei verschiedene Arten mit Git. Sie lösen unterschiedliche Probleme, und Sie können die eine, die andere oder beide verwenden. Sie zu verwechseln ist die häufigste Quelle für Verwirrung, also lassen Sie uns sie zuerst trennen.

Die erste Funktion ist die bidirektionale Synchronisierung über den Spec-First-Modus. Sie bearbeiten Ihr OpenAPI-Dokument als YAML oder JSON im IDE-ähnlichen Editor von Apidog, übernehmen Ihre Änderungen und pushen sie in den verbundenen Branch. Wenn jemand anderes die Spezifikation im Repository aktualisiert, ziehen Sie diese Änderungen zurück in Apidog. Dies ist ein echter Roundtrip: Bearbeitungen fließen zu Git, und Repository-Änderungen fließen zurück.

Die zweite Funktion ist die automatische Git-Sicherung von API-Spezifikationen. Hier exportiert Apidog die OpenAPI/Swagger-Datei jedes Moduls und pusht sie nach einem Zeitplan in ein Repository. Dies ist unidirektional und hands-off. Sie konfigurieren es einmal, und das System hält eine versionierte Kopie Ihrer Spezifikationen in Git, ohne dass Sie einen Finger rühren müssen. Es ist ein Sicherheitsnetz, kein Bearbeitungsworkflow.

Behalten Sie diesen Unterschied für den Rest des Artikels im Hinterkopf. Wenn wir von „Synchronisierung“ sprechen, meinen wir den bidirektionalen Spec-First-Modus-Fluss. Wenn wir von „Backup“ sprechen, meinen wir den geplanten, unidirektionalen Export.

Unterstützte Git-Anbieter

Apidog unterstützt die drei Anbieter, die die meisten Teams bereits nutzen. GitHub und GitLab verbinden sich direkt über ihre nativen Autorisierungsflows. Azure DevOps verbindet sich über eine generische Git-Verbindung, die mit jedem Git-Host funktioniert, der Standard-HTTPS-Authentifizierung spricht.

Die generische Git-Verbindung ist der Notausgang. Wenn Ihr Host nicht namentlich GitHub oder GitLab ist, aber Standard-Git über HTTPS mit Token-Authentifizierung spricht, übernimmt die generische Verbindung dies in der Regel. Azure DevOps ist der prominente Fall, aber der gleiche Pfad deckt selbst gehostete Setups ab, die eine HTTPS-Klon-URL verfügbar machen.

Ihren Git-Anbieter verbinden

Der Verbindungsschritt ist der Ort, an dem Sie Apidog den Zugriff gewähren, den es zum Lesen und Schreiben Ihres Repositories benötigt. Die Mechanismen unterscheiden sich geringfügig je nach Anbieter, aber die Form ist dieselbe: autorisieren, ein Repository auswählen, einen Branch auswählen.

Für GitHub autorisieren Sie über den OAuth-Bildschirm von GitHub. Apidog fordert Repository-Zugriff an, um die Spezifikation lesen und Commits pushen zu können. Wenn das Repository zu einer Organisation gehört, kann GitHub die Anfrage über einen Organisationsadministrator leiten, der den Zugriff Dritter genehmigt. Persönliche Repositories werden sofort unter Ihrem eigenen Konto autorisiert.

Für GitLab spiegelt der Ablauf GitHub. Sie melden sich über den OAuth-Bildschirm von GitLab an und gewähren Repository-Zugriff. Selbstverwaltetes GitLab funktioniert, solange Apidog die Instanz über das Netzwerk erreichen kann.

Für Azure DevOps verwenden Sie die generische Git-Verbindung. Anstelle eines OAuth-Handshakes geben Sie die HTTPS-Klon-URL des Repositories und ein persönliches Zugriffstoken (PAT) an. Erstellen Sie das PAT in Azure DevOps mit Berechtigung zum Lesen und Schreiben von Code und fügen Sie es dann in Apidog ein. Das Token ist die Anmeldeinformation, die Apidog das Pushen von Commits ermöglicht, also beschränken Sie dessen Gültigkeitsbereich genau auf die Repositories, die es benötigt.

Einige Hinweise zu Berechtigungen, die Zeit sparen:

• Organisation vs. persönliche Repositories. Organisations-Repositories erfordern oft eine einmalige Genehmigung der Integration durch einen Administrator. Wenn Ihre Autorisierung erfolgreich zu sein scheint, Apidog das Repository aber nicht sehen kann, fehlt in der Regel eine Administratorgenehmigung.
• Beschränken Sie den Gültigkeitsbereich des Tokens streng. Für Azure DevOps und jede generische Verbindung gewähren Sie dem PAT nur Lese-/Schreibzugriff auf Code für das Zielprojekt. Vermeiden Sie tokens mit vollem Kontozugriff.
• Private Repositories sind in Ordnung. Apidog funktioniert mit privaten Repositories. Der Zugriff erfolgt über die von Ihnen bereitgestellte Autorisierung oder das Token, nicht über die öffentliche Sichtbarkeit.

Sobald der Anbieter verbunden ist, erstellen Sie das Apidog-Projekt aus einem Repository plus einem Branch, typischerweise main. Diese Paarung bindet Ihre Spezifikationen an einen bestimmten Ort in der Versionskontrolle. Wenn Sie neu in der breiteren Praxis sind, behandelt unser Leitfaden zur OpenAPI-Versionskontrolle mit Git die Konventionen, die es wert sind, übernommen zu werden, bevor Sie alles einrichten.

Bidirektionale Synchronisierung mit dem Spec-First-Modus

Der Spec-First-Modus ist der Ort, an dem die bidirektionale Synchronisierung stattfindet. Er verwandelt Apidog in einen Spezifikationseditor, der Commits in Git ausführt wie jeder andere Code. Die vollständige Referenz finden Sie in der offiziellen Apidog-Dokumentation; hier erfahren Sie, wie der Roundtrip in der Praxis funktioniert.

Sie bearbeiten das OpenAPI-Dokument direkt als YAML oder JSON. Der Editor ist IDE-ähnlich: Er bietet Syntax-Hervorhebung, Live-Validierung und Auto-Vervollständigung, sodass ein falsch formatierter $ref oder ein fehlendes Pflichtfeld bereits während der Eingabe und nicht erst nach dem Push auftaucht. Während Sie bearbeiten, analysiert die linke Seitenleiste das Dokument automatisch in eine Gliederung, Pfade, Operationen und Schemas, sodass Sie eine große Spezifikation navigieren können, ohne durch den Rohtext scrollen zu müssen.

Eine typische Bearbeitung sieht so aus. Nehmen wir an, Sie fügen einen Endpunkt hinzu:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

Wenn Sie diese Änderung speichern, stuft Apidog sie als lokale Bearbeitung ein. Sie committen dann mit einer Nachricht und pushen in den verbundenen Branch, genau wie bei jedem anderen Git-Workflow. Nachdem der Push erfolgt ist, zeigt ein Synchronisierungsindikator „Gerade synchronisiert“ an – Ihre Bestätigung, dass Apidog und der Branch denselben Inhalt haben.

Die Pull-Richtung ist genauso wichtig. Wenn ein Teamkollege die Spezifikation im Repository bearbeitet und pusht, ziehen Sie diese Änderungen in Apidog, um Ihre lokale Kopie auf den neuesten Stand zu bringen. Das macht die Integration wirklich bidirektional: Das Repository ist nicht nur ein Backup-Ziel, es ist ein Peer.

Wenn Sie Änderungen vorgenommen haben, die Sie nicht behalten möchten, können Sie nicht gepushte Änderungen vor dem Commit verwerfen. Dadurch wird Ihre Arbeitskopie auf den letzten synchronisierten Zustand zurückgesetzt, was praktisch ist, wenn Sie experimentieren und entscheiden, dass die Änderung nicht beibehalten werden sollte.

Dieser Commit- und Push-Rhythmus ist das Herzstück eines Git-nativen API-Workflows: Spezifikationsänderungen durchlaufen dieselbe Überprüfungs-, Historien- und Rollback-Maschinerie wie der Rest Ihrer Codebasis. Reviewer kommentieren den YAML-Diff in einem Pull Request, Genehmigungen regeln das Mergen, und Ihre API-Designhistorie liest sich wie Ihre Codehistorie.

Automatische Git-Sicherung von API-Spezifikationen

Die Backup-Funktion ist die leisere Hälfte der Apidog Git-Integration, und sie verlangt nach der Einrichtung fast nichts von Ihnen. Sie weisen einem Modul ein Repository zu, und Apidog erledigt den Rest.

Hier ist der Mechanismus. Apidog kann die OpenAPI/Swagger-Datei für jedes Modul in einem Git-Repository sichern; GitHub, GitLab und Azure DevOps werden alle unterstützt. Sobald Sie die Backup-Konfiguration gespeichert haben, pusht das System die OpenAPI-Spezifikationsdatei des Moduls automatisch in das angegebene Repository. Der Push erfolgt während eines zufällig gewählten Zeitfensters außerhalb der Spitzenzeiten in der Nacht, was ihn außerhalb Ihrer Arbeitszeiten hält und die Last verteilt.

Gespeichert wird das exportierte OpenAPI/Swagger-Dokument für dieses Modul, ein Schnappschuss des API-Vertrags in seinem aktuellen Zustand. Da jeder Push ein Commit ist, sammeln Sie eine Versionshistorie in Git an. Sie können den Vertrag der letzten Woche mit dem heutigen vergleichen, genau sehen, wann ein Feld geändert wurde, und bei Bedarf eine frühere Version direkt aus dem Repository wiederherstellen.

Der Backup-Fluss ist per Design unidirektional. Apidog schreibt in das Repository; es liest keine Änderungen daraus zurück. Wenn Sie möchten, dass Repository-Bearbeitungen in Apidog fließen, ist das die Aufgabe des Spec-First-Modus, nicht des Backups. Verwenden Sie Backup, wenn Ihr Ziel Haltbarkeit und Historie ist, ohne die tägliche Arbeitsweise Ihres Teams zu ändern.

Auswahl eines Branches und der Repository-Struktur

Die strukturellen Entscheidungen, die Sie im Voraus treffen, prägen, wie reibungslos sich die Integration später anfühlt. Zwei Fragen dominieren: welcher Branch und wie viele Repositories.

Branch-Wahl. Die meisten Teams synchronisieren mit main für die kanonische Spezifikation und verwenden Feature-Branches für das laufende Design. Wenn Sie Apidog auf einen Feature-Branch verweisen, können Sie eine Spezifikationsänderung isoliert iterieren, einen Pull Request öffnen und mergen, sobald die Überprüfung bestanden ist – Ihr API-Design folgt demselben Branching-Modell wie Ihr Code. Apidog direkt auf main zu verweisen ist einfacher, überspringt aber die Review-Kontrolle, daher ist es kleinen Teams oder Änderungen mit geringem Risiko vorbehalten.

Ein Repository oder viele. Es gibt keine einzige richtige Antwort, aber die Kompromisse sind klar:

• Ein Repository pro API hält die Historie jeder Spezifikation sauber und ihre Zugriffskontrollen eng gefasst. Es ist die natürliche Wahl, wenn verschiedene Teams unterschiedliche APIs besitzen.
• Ein Monorepo für alle Spezifikationen zentralisiert alles und vereinfacht die API-übergreifende Suche und Überprüfung. Es funktioniert gut, wenn ein Plattformteam die API-Oberfläche besitzt. Halten Sie das Verzeichnislayout einfach, ein Ordner pro Modul, damit Backups und Synchronisierungen nicht kollidieren.

Wenn Sie ein Monorepo betreiben, geben Sie jedem Modul einen eigenen Pfad. Das hält die automatischen Backups ordentlich und macht Spezifikations-Diffe in der Überprüfung leicht lesbar.

Team-Berechtigungen und Zugriff

Die Git-Integration berührt Anmeldeinformationen, daher ist es wichtig, genau zu überlegen, wer was tun darf. Berechtigungen befinden sich an zwei Stellen: innerhalb von Apidog und innerhalb Ihres Git-Anbieters.

Innerhalb von Apidog werden die Teamberechtigungen während der Projekteinrichtung konfiguriert. Dort entscheiden Sie, wer mit dem verbundenen Repository synchronisieren und pushen kann. Beschränken Sie die Push-Rechte auf die Personen, die die Spezifikation besitzen, und lassen Sie alle anderen lesen. Dies verhindert versehentliche Pushes von Mitwirkenden, die lediglich das API-Design durchsuchen.

Innerhalb Ihres Git-Anbieters sind die Anmeldeinformationen wichtig. Bei GitHub und GitLab trägt die OAuth-Autorisierung den Zugriff des Benutzers, der sie erteilt hat. Für Azure DevOps und generische Verbindungen ist das persönliche Zugriffstoken die Anmeldeinformation; behandeln Sie es wie ein Geheimnis. Fügen Sie Token nicht in geteilte Dokumente ein, beschränken Sie ihren Gültigkeitsbereich nur auf die Ziel-Repositories und rotieren Sie sie im gleichen Rhythmus, wie Sie andere Geheimnisse rotieren. Wenn jemand das Team verlässt, widerrufen Sie dessen Token und autorisieren Sie neu unter einem noch aktiven Konto.

Das Prinzip ist einfach: Die Integration ist nur so sicher wie das schwächste Token dahinter. Halten Sie die Gültigkeitsbereiche eng und die Eigentumsverhältnisse klar.

Umgang mit Merge-Konflikten und Drift

Da Apidog echte Git-Historie committet, erbt es das Konfliktmodell von Git und dessen Werkzeuge zur Konfliktlösung. Konflikte treten auf, wenn zwei Personen denselben Teil der Spezifikation ändern, bevor sie synchronisieren.

Stellen Sie sich das Szenario vor. Sie bearbeiten das Order-Schema in Apidog und pushen. Ein Teamkollege hat dasselbe Schema auf der Repository-Seite bearbeitet und zuerst gepusht. Wenn Sie versuchen, dies abzugleichen, meldet Git einen Konflikt in der YAML-Datei, da beide Seiten überlappende Zeilen geändert haben. Dies ist kein Apidog-Problem; es ist ein normaler Git-Merge-Konflikt in einer YAML-Datei, und Sie lösen ihn auf die normale Weise.

Um Konflikte zu vermeiden, pullen Sie, bevor Sie pushen. Das Einholen des neuesten Repository-Zustands in Apidog, bevor Sie Ihre eigenen Änderungen committen, hält Ihre Arbeitskopie aktuell und verkürzt das Zeitfenster, in dem zwei Bearbeitungen kollidieren können. Wenn ein Konflikt auftritt, lösen Sie ihn in der YAML-Datei auf dieselbe Weise, wie Sie jeden Merge-Konflikt lösen würden: Wählen Sie die richtigen Zeilen aus, halten Sie das Dokument gültig und synchronisieren Sie erneut. Die Live-Validierung des Editors hilft hier: Ein verpatzter Merge, der die OpenAPI-Struktur bricht, zeigt sich sofort und nicht erst nach dem Push.

Drift, bei der Apidog und das Repository stillschweigend auseinanderlaufen, ist die langsame Version desselben Problems. Die Anzeige „Gerade synchronisiert“ ist Ihre Frühwarnung. Wenn sie nicht „synchronisiert“ anzeigt, ist etwas nicht gepusht oder gepullt. Betrachten Sie dies als Aufforderung zur Abstimmung, bevor die Lücke größer wird.

Fehlerbehebung

Die meisten Integrationsprobleme lassen sich auf Authentifizierung, Branch-Auswahl oder eine unterbrochene Synchronisierung zurückführen. Arbeiten Sie die Tabelle durch, bevor Sie annehmen, dass etwas tiefer Liegendes falsch ist.

Wenn die Autorisierung das wiederkehrende Thema ist, und das ist sie in der Regel, beginnen Sie damit, zu bestätigen, dass die Anmeldeinformationen aktiv und korrekt eingerichtet sind. Ein widerrufenes Token oder eine fehlende Organisationsgenehmigung erklärt die Mehrheit der Berichte „es funktioniert einfach nicht mehr“.

FAQ

Ist die Synchronisierung unidirektional oder bidirektional?

Das hängt davon ab, welche Funktion Sie verwenden. Der Spec-First-Modus ist bidirektional: Sie pushen Änderungen zu Git und pullen Repository-Änderungen zurück in Apidog. Das automatische Backup ist unidirektional: Apidog exportiert die Spezifikation jedes Moduls nach einem Zeitplan in das Repository und liest keine Änderungen zurück.

Wo werden meine Spezifikationen gespeichert?

Im Git-Repository, das Sie verbinden. Im Spec-First-Modus befindet sich Ihr OpenAPI-Dokument auf dem Branch, in den Sie pushen. Für die automatische Sicherung wird die exportierte OpenAPI/Swagger-Datei jedes Moduls in das von Ihnen konfigurierte Repository committet. In beiden Fällen enthält Git die versionierte Kopie, und Sie behalten die volle Kontrolle über das Repository.

Mit welchem Branch sollte ich synchronisieren?

Verwenden Sie main für die kanonische Spezifikation und Feature-Branches für laufende Änderungen. Das Synchronisieren mit einem Feature-Branch ermöglicht es einer Spezifikationsänderung, einen Pull Request und eine Überprüfung zu durchlaufen, bevor sie gemergt wird, was widerspiegelt, wie Ihr Code bereits durch Git bewegt wird.

Was passiert, wenn mein Token widerrufen wird?

Pushes schlagen fehl, weil Apidog keinen Schreibzugriff mehr hat. Autorisieren Sie den Anbieter neu, oder generieren Sie für Azure DevOps und generische Verbindungen ein neues persönliches Zugriffstoken und aktualisieren Sie es in Apidog. Sobald die Anmeldeinformationen wiederhergestellt sind, werden Synchronisierung und Backup normal fortgesetzt.

Fazit

Die Apidog Git-Integration bietet Ihnen zwei sich ergänzende Tools: eine bidirektionale Synchronisierung über den Spec-First-Modus für Teams, die die Spezifikation als Code behandeln, und eine automatische Backup-Funktion pro Modul für alle, die einfach ein versioniertes Sicherheitsnetz wünschen. Beide funktionieren mit GitHub, GitLab und Azure DevOps, sodass Sie den Anbieter verbinden können, den Sie bereits nutzen, anstatt einen neuen einzuführen.

Wählen Sie die Funktion, die Ihrem Ziel entspricht. Wenn Sie Überprüfung und Historie bei jeder Spezifikationsänderung wünschen, richten Sie den Spec-First-Modus ein und übernehmen Sie den Commit-und-Push-Rhythmus. Wenn Sie Beständigkeit wünschen, ohne Ihren Workflow zu ändern, aktivieren Sie das Backup und lassen Sie den nächtlichen Push dies erledigen. Viele Teams verwenden beides. Wenn Sie bereit sind, es zu verbinden, verbinden Sie Ihren Anbieter, weisen Sie ein Projekt einem Repository und einem Branch zu und lassen Sie Ihre API-Spezifikationen dort leben, wo der Rest Ihrer Arbeit bereits ist.