Kurz gesagt: Ein Git-nativer API-Arbeitsplatz bedeutet: Ihre API-Spezifikationen liegen in Git als Source of Truth, inklusive Versionskontrolle, Branching und Merge-Request-Workflows direkt in der API-Entwicklungsplattform. Teams arbeiten in isolierten Sprint-Branches, prüfen Änderungen über Merge-Requests und synchronisieren automatisch mit ihren Repositories. Der Spec-first-Modus von Apidog unterstützt diesen Workflow mit OpenAPI-Bearbeitung, Echtzeit-Validierung und GitHub/GitLab/Azure DevOps-Integration.
Probieren Sie Apidog noch heute aus
Warum API-Teams Git-native Workflows benötigen
Viele API-Teams haben dieselben wiederkehrenden Probleme:
„Welche Version der Spezifikation ist aktuell?“
Mehrere Personen bearbeiten dieselbe Sammlung oder Datei, aber niemand weiß, welche Version autoritativ ist.„Warum hat sich dieser Endpunkt geändert?“
Ohne Git-Historie fehlt ein nachvollziehbares Änderungsprotokoll.„Kann ich an einer neuen Funktion arbeiten, ohne die Hauptspezifikation zu beschädigen?“
Direkte Bearbeitung der Live-Spezifikation führt schnell zu Konflikten.„Wie reviewen wir diese API-Änderung?“
Screenshots, Slack-Nachrichten oder JSON-Snippets ersetzen keinen strukturierten Review-Prozess.
Das sind keine reinen Tool-Probleme. Es sind Workflow-Probleme.
Der etablierte Workflow für Code existiert bereits: Git.
Backend-, Frontend- und DevOps-Teams arbeiten täglich mit Branches, Pull Requests, Reviews und CI/CD. API-Design lebt jedoch häufig außerhalb dieses Systems — obwohl die API-Spezifikation den Vertrag zwischen Systemen beschreibt und damit genauso kritisch ist wie Anwendungscode.
Ein Git-nativer Ansatz bringt API-Design in denselben Workflow wie Code: Branch erstellen, Spezifikation ändern, validieren, reviewen, mergen.
Was „Git-nativ“ für APIs bedeutet
Git-nativ heißt nicht nur: „Die OpenAPI-Datei liegt irgendwo im Repository.“
Das reicht oft nicht aus, wenn die Bearbeitung weiterhin in separaten Tools passiert und Git nur als Exportziel dient.
| Traditionelle Git-Speicherung | Git-nativer Arbeitsplatz |
|---|---|
| Spezifikationen liegen in Git, werden aber extern bearbeitet | Spezifikationen werden direkt im API-Arbeitsbereich bearbeitet, Git bleibt Source of Truth |
| Manuelle Commits nach der Bearbeitung | Commit und Push direkt aus dem API-Arbeitsbereich |
| Kein API-spezifisches Branching | Sprint-Branches für isolierte Feature-Entwicklung |
| YAML-Diffs werden mühsam in Code-Review-Tools geprüft | Merge-Requests mit API-orientierter Änderungsansicht |
| Synchronisierung bricht, wenn jemand außerhalb des Tools ändert | Zwei-Wege-Synchronisierung mit Git als primärer Quelle |
Ein Git-nativer API-Arbeitsplatz behandelt Ihr Repository als autoritative Quelle. Bearbeitung, Branching, Review und Synchronisierung basieren auf Git.
Kernkomponenten
Spec-first-Modus
OpenAPI YAML/JSON-Dateien sind das primäre Artefakt.Sprint-Branches
API-Feature-Branches für isolierte Arbeit.Geschützter Haupt-Branch
Änderungen landen nur nach Review im stabilen Branch.Merge-Requests
Strukturierte Reviews mit Vorher-/Nachher-Vergleichen.Webhook-Synchronisierung
Pushes ins Repository werden automatisch mit Apidog synchronisiert.
Das Problem mit traditionellen API-Tools
Viele API-Plattformen arbeiten nach einem internen Datenbankmodell:
- Endpunkte werden über visuelle Formulare erstellt.
- Die Plattform speichert alles intern.
- OpenAPI wird bei Bedarf exportiert.
- Git-Historie entsteht nur, wenn jemand manuell exportiert und committet.
Für Einzelpersonen kann das funktionieren. Für Teams erzeugt es Reibung.
Keine echte Git-Historie
Eine interne Änderungshistorie ersetzt keine Git-Historie. Ohne Git-native Arbeitsweise können Teams oft nicht:
- nachvollziehen, wer wann was geändert hat
- sauber Branches erstellen und zusammenführen
- mit Git-Befehlen zu einem früheren Zustand zurückkehren
- CI/CD-Pipelines zuverlässig an Spezifikationsänderungen koppeln
Konflikte bei paralleler Arbeit
Wenn mehrere Personen gleichzeitig an API-Definitionen arbeiten:
- überschreiben sich Änderungen leichter
- Merge-Konflikte sind schwer aufzulösen
- Work-in-Progress landet zu früh in der Hauptspezifikation
Review-Lücken
Ohne Git-nativen Review-Prozess läuft API-Review oft über:
- UI-Screenshots
- kopierte JSON/YAML-Snippets
- manuelle Kommentare in Tickets
- unvollständige Diff-Ansichten
Das skaliert schlecht und erzeugt wenig Auditierbarkeit.
Apidogs Git-nativer Ansatz: Spec-first-Modus
Apidogs Spec-first-Modus dreht das Modell um:
Git ist die Source of Truth. Apidog ist die Arbeitsoberfläche dafür.
Einrichtung: Spec-first-Projekt verbinden
Der Workflow sieht so aus:
Git-Anbieter verbinden
Unterstützt werden GitHub, GitLab, Azure DevOps und Bitbucket.Repository und Haupt-Branch auswählen
Apidog liest vorhandene OpenAPI-Dateien oder startet mit einem neuen Stand.Im Specs-Arbeitsbereich bearbeiten
Änderungen erfolgen direkt an YAML/JSON-Dateien.Commit & Push aus Apidog ausführen
Änderungen landen direkt im verbundenen Repository.Synchronisierung aktivieren
Webhooks halten Repository und Apidog automatisch aktuell.
Arbeiten im Spezifikations-Arbeitsbereich
Im Spec-first-Modus arbeiten Sie dateibasiert:
Dateiexplorer
Zugriff auf die Repository-Struktur.API-Strukturbaum
Geparste OpenAPI-Inhalte wie Endpunkte, Schemas und Komponenten.Code-Editor
YAML/JSON-Bearbeitung mit Validierung, Autovervollständigung und Syntaxhervorhebung.Formular-Editor
Strukturierte Bearbeitung unterstützter OpenAPI-Knoten, ohne die Datei als Quelle zu ersetzen.
Sie können vollständig in YAML/JSON arbeiten oder für bestimmte Ressourcen in die Formularansicht wechseln. Entscheidend bleibt: Die zugrunde liegende Datei in Git ist maßgeblich.
Validierung vor dem Commit
Der Editor unterstützt:
Validierungspanel
Erkennt Syntaxfehler, fehlende Pflichtfelder und OpenAPI-Regelverletzungen.Vorschaupanel
Zeigt, wie die Spezifikation als Dokumentation gerendert wird.Ausprobieren-Funktion
Endpunkte können direkt aus der Spezifikation getestet werden.
Praktischer Effekt: Fehlerhafte Spezifikationen werden früher erkannt — nicht erst in CI.
Sprint-Branches: API-Feature-Branches
In der Code-Entwicklung sind Feature-Branches Standard. Dasselbe Prinzip ist für API-Spezifikationen sinnvoll.
Mit Sprint-Branches arbeiten Teams isoliert an API-Änderungen, ohne den Haupt-Branch zu destabilisieren.
Typische Szenarien
| Szenario | Ohne Sprint-Branches | Mit Sprint-Branches |
|---|---|---|
| Neuer Endpunkt | Direkte Änderung der Hauptspezifikation | Isolierte Entwicklung bis zur Freigabe |
| API-Tests | Tester sehen unfertige Änderungen | Tester wechseln gezielt auf den Sprint-Branch |
| Parallele Features | Änderungen kollidieren in einer Spezifikation | Jedes Feature hat einen eigenen Branch |
| Rollback | Änderungen müssen manuell rückgängig gemacht werden | Branch kann verworfen oder selektiv gemergt werden |
Sprint-Branch erstellen
- Branch-Umschalter neben APIs öffnen.
- Neuer Sprint-Branch wählen.
- Branch nach Feature benennen, z. B.
user-authentication-v2. - Änderungen isoliert vom Haupt-Branch durchführen.
Sprint-Branch befüllen
Option 1: API-first
Verwenden Sie Fork from main, um Endpunkte, Schemas oder Komponenten aus dem Haupt-Branch zu übernehmen.
Apidog verfolgt die Zuordnung, damit beim späteren Merge klar ist, welche Ressourcen geändert wurden.
Option 2: Code-first / OAS-Import
Wenn Ihr Backend bereits eine aktualisierte OpenAPI-Spezifikation erzeugt, importieren Sie diese in den Sprint-Branch.
Apidog vergleicht die importierte Spezifikation mit dem Haupt-Branch und übernimmt nur die geänderten Ressourcen.
Tests an Branch-Änderungen anpassen
Ein häufiger Fehler: Ein Endpunkt wird im Sprint-Branch geändert, aber bestehende Tests zeigen weiterhin auf die Hauptversion.
Apidog unterstützt dabei durch:
- Markierung geänderter Endpunkte in Testszenarien
- Möglichkeit, Tests für Sprint-Branch-Versionen zu duplizieren
- Abgleich zwischen Tests und Branch-Stand
So werden API-Änderungen und Tests gemeinsam aktualisiert, bevor sie in den Haupt-Branch gelangen.
Geschützte Branches und Merge-Requests
Ein geschützter Haupt-Branch verhindert direkte Änderungen an produktionsnahen API-Spezifikationen.
In Apidog bedeutet das:
Keine direkten Bearbeitungen
Änderungen müssen über Merge-Requests laufen.Verpflichtender Review
Administratoren prüfen und genehmigen vor dem Merge.Audit-Trail
Jede Änderung ist mit einem Review-Vorgang verbunden.
Merge-Request erstellen
Wenn die Arbeit im Sprint-Branch bereit ist:
- Im Branch-Umschalter auf Merge klicken.
- Änderungen prüfen.
Apidog markiert Ressourcen nach Status:
- Grau — unverändert
- Orange — geändert
- Grün — neu
Danach:
- Unterschiede zwischen Sprint- und Hauptversion prüfen.
- Auswählen, welche Ressourcen gemergt werden sollen.
- Merge-Request erstellen oder bei ungeschützten Branches direkt mergen.
Review durchführen
Reviewer sehen:
- vollständige Änderungsliste
- Vorher-/Nachher-Vergleiche
- Kontext aus dem Sprint-Branch
Sie können Änderungen genehmigen, ablehnen oder Anpassungen anfordern.
Wenn der Entwickler den Sprint-Branch weiter aktualisiert, wird der bestehende Merge-Request automatisch aktualisiert. Es muss kein neuer Request erstellt werden.
Git-Operationen in Apidog: Commit, Push, Pull
Git-Operationen können direkt im Apidog-Arbeitsbereich ausgeführt werden.
Commit & Push
Nach der Bearbeitung:
- Änderungen öffnen.
- Geänderte, hinzugefügte und gelöschte Dateien prüfen.
- Dateien auswählen, die in den Commit sollen.
- Commit-Nachricht schreiben.
- Push ausführen.
Die Änderungen werden direkt ins verbundene Repository übertragen.
Git Pull
Wenn andere Teammitglieder Änderungen ins Repository pushen:
- Branch-Namen in der Specs-Sidebar öffnen.
- Git Pull wählen.
- Aktuelle Dateien nach Apidog synchronisieren.
Webhook-Synchronisierung
Wenn Sie Admin-Zugriff auf das Repository haben, empfiehlt sich die Webhook-Einrichtung:
- Pushes ins Repository lösen automatische Synchronisierung aus.
- Manuelle Pulls werden seltener nötig.
- Das Team arbeitet einfacher auf dem aktuellen Stand.
Ohne Webhook funktioniert der manuelle Pull weiterhin.
Vorher vs. nachher
| Vorher | Nachher |
|---|---|
| Entwickler ändern die Hauptspezifikation direkt | Arbeit in isolierten Sprint-Branches |
| Tester sehen unfertige Änderungen | Tester wechseln gezielt auf Branches |
| Review über Screenshots und Slack | Merge-Requests mit Diffs |
| Parallele Arbeit ist schwer sichtbar | Branch-Umschalter zeigt aktive Arbeiten |
| Merges können Änderungen überschreiben | Selektiver Merge mit Vorschau |
Git-native API-Entwicklung fügt nicht primär Komplexität hinzu. Sie fügt Struktur hinzu, die Teamarbeit nachvollziehbarer macht.
FAQ
Was ist der Unterschied zwischen Spec-first-Modus und regulären Apidog-Projekten?
Der Spec-first-Modus verwendet Ihr Git-Repository als Source of Truth. Reguläre Apidog-Projekte verwenden Apidogs interne Datenbank als primäre Quelle und Git-Export als sekundären Mechanismus.
Im Spec-first-Modus bearbeiten Sie Dateien direkt, committen von Apidog aus nach Git und synchronisieren Änderungen automatisch oder manuell.
Kann ich ein bestehendes Apidog-Projekt in den Spec-first-Modus wechseln?
Derzeit erfordert der Spec-first-Modus ein neues Projekt, das mit einem Git-Repository verbunden wird. Sie können die OpenAPI-Spezifikation eines bestehenden Projekts exportieren und in das neue Spec-first-Projekt importieren.
Welche Git-Anbieter werden unterstützt?
Apidog unterstützt GitHub, GitLab, Azure DevOps und Bitbucket für Spec-first-Projekte.
Benötige ich Administratorrechte für mein Repository?
Administratorrechte sind erforderlich, um Webhooks zu installieren. Diese ermöglichen automatische Synchronisierung bei Pushes ins Repository.
Ohne Webhook können Sie weiterhin manuell per Git Pull synchronisieren. Schreibrechte reichen aus, um Änderungen aus Apidog zu pushen.
Kann ich den Spec-first-Modus mit einem leeren Repository verwenden?
Ja. Wenn das Repository keine vorhandenen OpenAPI-Dateien enthält, starten Sie mit einer neuen Spezifikation im Specs-Arbeitsbereich und pushen den ersten Commit ins Repository.
Wie unterscheiden sich Sprint-Branches von Git-Branches?
Sprint-Branches in Apidog entsprechen Git-Branches im Repository. Wenn Sie einen Sprint-Branch erstellen, wird ein entsprechender Git-Branch erstellt. Änderungen werden mit diesem Branch synchronisiert.
Was passiert, wenn jemand das Git-Repository direkt bearbeitet?
Wenn Webhook-Synchronisierung eingerichtet ist, lösen Pushes ins Repository eine automatische Synchronisierung mit Apidog aus.
Ohne Webhook verwenden Sie Git Pull, um die Änderungen in Apidog zu übernehmen.
Kann ich Spezifikationen sowohl in der Code-Ansicht als auch in der Formularansicht bearbeiten?
Ja. Der Specs-Arbeitsbereich enthält einen Code-Editor für YAML/JSON und eine Formularansicht für unterstützte OpenAPI-Knoten wie Endpunkte, Schemas und Definitionen.
Beide Ansichten aktualisieren dieselbe zugrunde liegende Datei in Git.
Wie funktionieren Merge-Requests für Testszenarien?
Testszenarien werden getrennt von Endpunkten und Schemas zusammengeführt. Nachdem API-Ressourcen in den Haupt-Branch gemergt wurden, können Testszenarien aus dem Sprint-Branch über Merge to Main übernommen werden.
Derzeit können nur Projektadministratoren Testszenarien in geschützte Haupt-Branches mergen.
Top comments (0)