Wenn Ihr OpenAPI-Dokument in einem Git-Repository liegt, Sie es aber in einem API-Client bearbeiten, kennen Sie das Problem bereits: Die YAML-Datei kopieren, wieder einfügen, hoffen, dass niemand sonst die Datei berührt hat, und beten, dass der Import nicht stillschweigend ein Feld gelöscht hat. Ein Spec und ein Repo manuell synchron zu halten, ist die Art von mühsamer Arbeit, die genau dann schiefgeht, wenn man es eilig hat.
Diese Anleitung zeigt Ihnen, wie Sie Ihre OpenAPI-Spezifikation mit dem Spec-First-Modus von Apidog mit GitHub synchronisieren, sodass die Spezifikation in Ihrem Repo und die Spezifikation in Ihrem Editor dasselbe bleiben, anstatt zwei Kopien, die Sie ständig abgleichen müssen. Wir werden einen Anbieter verbinden, ein Projekt direkt aus einem Repo öffnen, die YAML bearbeiten und die Änderung in einem Durchgang zurück zu GitHub pushen. Die gleichen Schritte funktionieren auch für GitLab.
Legen wir los.
Was bidirektionale Synchronisierung wirklich bedeutet
Bidirektionale Synchronisierung bedeutet, dass Bearbeitungen automatisch in beide Richtungen fließen, ohne einen Export-Schritt dazwischen.
- Apidog zu Git: Wenn Sie das OpenAPI-Dokument in Apidog bearbeiten und committen, wird die Änderung als normaler Git-Commit auf dem von Ihnen gewählten Branch in Ihr Repository gepusht.
- Git zu Apidog: Wenn ein Teamkollege (oder Sie, von Ihrer IDE aus) eine Änderung an diesen Branch pusht, zieht Apidog diese zurück, sodass Ihr Editor widerspiegelt, was tatsächlich im Repo ist.
Das Repository ist die einzige Quelle der Wahrheit. Apidog ist ein umfangreicher Editor, der darauf aufbaut. Das ist die ganze Idee hinter einem Git-nativen API-Workflow: Die Spezifikation wird versioniert, überprüft und historisch nachverfolgt wie jede andere Datei in Ihrer Codebasis, anstatt in einem Tool zu liegen, das regelmäßig einen Snapshot exportiert.
Voraussetzungen
Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:
- Apidog installiert (Desktop-App oder Web), angemeldet.
- Ein GitHub- oder GitLab-Repository, das bereits ein OpenAPI-Dokument enthält, oder eines, für das Sie Schreibzugriff haben. Azure DevOps wird auch über Git Connection unterstützt.
- Spec-First-Modus (Beta) aktiviert. Dies ist der Modus, der Ihr Projekt in eine dünne Schicht über einem Git-Repo verwandelt, anstatt Apidogs eigenen Speicher zu nutzen.
Sie benötigen Schreibberechtigungen für den Branch, mit dem Sie synchronisieren möchten. Nur-Lese-Zugriff erlaubt Ihnen das Pull, aber nicht das Push.
Schritt 1: Verbinden Sie Ihren Git-Anbieter
Autorisieren Sie zuerst Apidog, mit Ihrem Anbieter zu kommunizieren.
- Öffnen Sie Apidog und erstellen Sie ein neues Projekt, wählen Sie den Spec-First-Modus.
- Wenn Sie aufgefordert werden, eine Quelle auszuwählen, wählen Sie Ihren Anbieter, GitHub oder GitLab.
- Klicken Sie auf Autorisieren. Ihr Browser öffnet den OAuth-Bildschirm des Anbieters.
- Erteilen Sie Apidog Zugriff auf die Repositories, die Sie synchronisieren möchten. Auf GitHub können Sie dies auf bestimmte Repositories statt auf Ihr gesamtes Konto beschränken.
Sobald die Autorisierung abgeschlossen ist, werden Sie mit dem verbundenen Anbieter zu Apidog zurückgeleitet. Dies müssen Sie nur einmal pro Anbieter tun, zukünftige Projekte verwenden die Verbindung wieder.
Für die vollständige Referenz zu diesem Ablauf, einschließlich Azure DevOps über Git Connection, siehe die Dokumentation zum Spec-First-Modus.
Schritt 2: Erstellen Sie ein Projekt aus einem Repo und Branch
Weisen Sie Apidog nun auf die eigentliche Spezifikation.
- Wählen Sie mit verbundenem Anbieter das Repository aus, das Ihre OpenAPI-Datei enthält.
- Wählen Sie den Branch aus, mit dem synchronisiert werden soll, normalerweise
main. Dies ist der Branch, auf dem Ihre Commits landen werden und den Apidog auf eingehende Änderungen überwacht. - Bestätigen Sie den Pfad zum OpenAPI-Dokument, falls Apidog danach fragt (zum Beispiel
openapi.yamlim Repo-Root oder unterdocs/). - Erstellen Sie das Projekt.
Apidog klont die Spezifikation von diesem Branch und öffnet sie. Die linke Seitenleiste füllt sich mit Ihren Endpunkten und Schemas, da Apidog das Dokument in eine navigierbare Gliederung geparst hat. Sie sehen nun die Spezifikation des Repos, live.
Schritt 3: Bearbeiten Sie Ihre OpenAPI-YAML im Code-Editor
Der Spec-First-Modus bietet Ihnen einen IDE-ähnlichen Editor für die rohe OpenAPI-YAML, mit Syntax-Hervorhebung, Inline-Validierung und Autovervollständigung. Sie schreiben OpenAPI direkt; Apidog hält die visuelle Gliederung beim Tippen synchron.
Fügen wir einen kleinen Endpunkt hinzu. Angenommen, Sie möchten einen Gesundheitscheck:
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 Sie tippen, passieren zwei Dinge. Die linke Seitenleiste parst die Gliederung automatisch, sodass Ihre neue /health-Operation sofort im Baum erscheint. Und der Validator kennzeichnet Probleme direkt, einen fehlenden responses-Block, einen fehlerhaften $ref, einen Einrückungsfehler, noch bevor Sie committen. Wenn die YAML fehlerhaft ist, sehen Sie es unterstrichen, anstatt es später in einer fehlgeschlagenen Pipeline zu entdecken.
Hier zahlt sich auch die Versionskontrolle aus. Wenn Sie einen tieferen Einblick wünschen, wie Diffs und Historie bei einer Spezifikation funktionieren, erklärt dies der Leitfaden zur OpenAPI-Versionskontrolle mit Git.
Schritt 4: Committen und pushen
Wenn die Bearbeitung korrekt aussieht, senden Sie sie an GitHub.
- Öffnen Sie das Commit-Panel (den Git-/Quellcodeverwaltungsbereich des Projekts).
- Überprüfen Sie die Änderung. Apidog zeigt an, was gegenüber der synchronisierten Version geändert wurde.
- Schreiben Sie eine Commit-Nachricht, behandeln Sie sie wie jeden anderen Commit:
Add /health endpoint. - Klicken Sie auf Committen & Pushen.
Apidog committet auf Ihren gewählten Branch und pusht zum Remote-Repository. Öffnen Sie Ihr Repository auf GitHub und Sie sehen den Commit in der Branch-Historie, wie erwartet verfasst und genau die OpenAPI-Datei betreffend.
Haben Sie Ihre Meinung vor dem Push geändert? Sie können nicht gepushte Bearbeitungen verwerfen, um das Dokument auf den letzten synchronisierten Zustand zurückzusetzen. Nichts verlässt Apidog, bevor Sie committen, sodass lokale Experimente lokal bleiben.
Schritt 5: Überprüfen Sie den Synchronisierungsstatus
Apidog zeigt eine Synchronisierungsanzeige, damit Sie immer wissen, wo Sie stehen.
Nach einem erfolgreichen Push zeigt die Anzeige „Gerade synchronisiert“ an. Das ist Ihre Bestätigung, dass der Editor und der Remote-Branch dasselbe Dokument enthalten. Mit der Zeit aktualisiert sich die Anzeige („Vor 5 Minuten synchronisiert“) und wenn jemand anderes pusht, zieht Apidog die Änderung und setzt die Anzeige nach dem Abgleich zurück.
Wenn die Anzeige einen ausstehenden oder veralteten Zustand anzeigt, bedeutet dies, dass die lokale Kopie und das Remote-Repository abgewichen sind. Dies ist Ihr Hinweis, vor dem Fortfahren zu pullen oder aufzulösen.
Fehlerbehebung
Einige Dinge neigen dazu, Menschen beim ersten Mal zu verwirren.
- Autorisierung abgelaufen oder widerrufen. Wenn Push-Vorgänge mit einem Berechtigungsfehler fehlschlagen, führen Sie die Autorisierung aus Schritt 1 erneut aus. Tokens können anbieterseitig widerrufen werden oder einfach ablaufen.
- Falscher Branch. Das Pushen auf einen geschützten
main-Branch, der Pull Requests erfordert, wird abgelehnt. Synchronisieren Sie entweder mit einem anderen Branch oder passen Sie die Schutzregeln des Branches an. Überprüfen Sie, ob der in Schritt 2 ausgewählte Branch mit dem übereinstimmt, wo Sie Commits erwarten. - Merge-Konflikte. Wenn ein Teamkollege auf denselben Branch gepusht hat, während Sie bearbeitet haben, ist das Remote-Repository Ihrer lokalen Kopie voraus. Ziehen Sie die neuesten Änderungen, gleichen Sie die überlappende YAML ab und committen Sie erneut. Da die Spezifikation reiner Text ist, werden Konflikte auf dieselbe Weise gelöst wie jeder Code-Konflikt.
- Validierungsfehler blockieren Ihren Workflow. Apidog wird Sie nicht daran hindern, ungültige YAML zu committen, aber Sie sollten zuerst beheben, was der Inline-Validator kennzeichnet. Eine saubere Spezifikation hält Ihre generierten Dokumente, Mocks und Tests ehrlich.
FAQ
Funktioniert die Synchronisierung mit GitHub 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 von Verbinden-Bearbeiten-Committen-Pushen ist bei allen dreien derselbe; nur der Autorisierungsbildschirm unterscheidet sich je nach Anbieter.
Was passiert, wenn ein Teamkollege die Spezifikation im Repo bearbeitet, während ich in Apidog arbeite?
Apidog zieht ihre Änderung als Teil der bidirektionalen Synchronisierung in Ihren Editor zurück. Wenn Ihre und ihre Bearbeitungen verschiedene Teile der Datei betreffen, werden sie sauber zusammengeführt. Wenn sie sich überschneiden, lösen Sie einen Standard-Git-Konflikt, genau wie Sie es in jeder Textdatei tun würden.
Kann ich eine Änderung rückgängig machen, bevor sie GitHub erreicht?
Ja. Bis Sie auf Committen & Pushen klicken, sind Ihre Bearbeitungen lokal. Verwenden Sie „Nicht gepushte Bearbeitungen verwerfen“, um das Dokument auf den letzten synchronisierten Zustand zurückzusetzen, und nichts gelangt zum Remote-Repository.