Ihre OpenAPI-Spezifikation ist der Vertrag zwischen Ihrer API und ihren Konsumenten. Damit dieser Vertrag nicht veraltet, sollte er dort liegen, wo Ihr Team ohnehin arbeitet: im Git-Repository.
Allzu oft liegen API-Spezifikationen in isolierten Tools: einmal exportiert, dann vergessen und selten aktualisiert, wenn sich die Implementierung ändert. Die Folge: Dokumentation driftet ab, Testsammlungen unterscheiden sich, und Reviewer genehmigen Codeänderungen, ohne die passenden Spezifikationsänderungen zu sehen.
Der Spec-first-Modus kehrt dieses Modell um. Ihre OpenAPI- oder Swagger-Dateien werden zur Source of Truth und liegen direkt neben dem Implementierungscode im Git-Repository. Jede Spezifikationsänderung läuft durch dieselben Branches, Pull Requests und Reviews wie Ihr Code. API-Design, Tests und Dokumentation bleiben dadurch synchron.
In diesem Tutorial richten Sie ein Spec-first-Projekt in Apidog ein, bearbeiten Spezifikationen im Team und synchronisieren Änderungen mit Ihrem Git-Workflow.
Was ist der Spec-first-Modus?
In einem klassischen API-Projekt erstellen Sie Endpunkte häufig über visuelle Formulare oder importieren eine bestehende Spezifikation als Startpunkt. Das Tool speichert API-Definitionen intern, und Git ist höchstens ein Exportziel.
Der Spec-first-Modus ist dateibasiert:
-
openapi.yamloderopenapi.jsonliegen in Ihrem Repository - Apidog parst diese Dateien und erzeugt daraus eine navigierbare API-Struktur
- Sie bearbeiten die Spezifikation direkt als Datei oder über unterstützte Formulare
- Änderungen werden mit Git synchronisiert
Die Spezifikationsdatei bleibt maßgebend. Apidog liest daraus, schreibt hinein und hält sie mit Ihrem Repository synchron.
Voraussetzungen
Für die Umsetzung benötigen Sie:
- Ein Apidog-Konto, die kostenlose Version reicht aus
- Ein Git-Repository mit einer OpenAPI-/Swagger-Datei oder ein leeres Repository
- Schreibzugriff auf das Repository
- Grundkenntnisse der OpenAPI- oder Swagger-Syntax
Eine minimale OpenAPI-Datei kann zum Beispiel so aussehen:
openapi: 3.0.3
info:
title: Beispiel API
version: 1.0.0
paths:
/users:
get:
summary: Benutzer auflisten
responses:
"200":
description: Erfolgreiche Antwort
Schritt 1: Spec-first-Projekt erstellen
Öffnen Sie Apidog und erstellen Sie ein neues Projekt:
- Klicken Sie auf + Neues Projekt
- Wählen Sie Spec-first-Modus
- Verbinden Sie Ihren Git-Anbieter
- Wählen Sie Repository und Branch aus
- Schließen Sie die Projekterstellung ab
Unterstützte Git-Anbieter sind unter anderem:
- GitHub
- GitLab
- Azure DevOps
- Bitbucket
Apidog synchronisiert sich mit dem Standard-Branch Ihres Repositories. Wenn dieser nicht main heißt, verwendet Apidog automatisch den entsprechenden Standard-Branch.
Schritt 2: Webhook-Synchronisierung konfigurieren
Während der Einrichtung können Sie einen Webhook installieren. Damit synchronisiert Apidog automatisch, sobald Ihr Team Änderungen in das Repository pusht.
Hinweis: Die Webhook-Installation erfordert normalerweise Administratorrechte für das Repository. Wenn Sie diese nicht haben, können Sie den Schritt überspringen und später manuell per Git Pull synchronisieren.
Der Webhook ist sinnvoll, wenn mehrere Personen an derselben Spezifikation arbeiten:
- Team pusht Änderungen
- Apidog erkennt das Push-Event
- Die Spezifikation wird automatisch aktualisiert
- Alle sehen denselben Stand
Falls Sie den Webhook bei der Einrichtung übersprungen haben, können Sie ihn später unter Projekteinstellungen > Git & Branches hinzufügen.
Schritt 3: Spezifikations-Arbeitsbereich öffnen
Nach der Erstellung öffnet Apidog den Spezifikations-Arbeitsbereich. Dort bearbeiten Sie Dateien und führen Git-Operationen aus.
Der Arbeitsbereich besteht aus drei zentralen Bereichen:
| Panel | Aufgabe |
|---|---|
| Dateiexplorer | Zeigt Dateien und Ordner aus dem synchronisierten Repository |
| API-Strukturbaum | Zeigt geparste OpenAPI-Inhalte wie Endpunkte, Schemas und Definitionen |
| Editor | Bearbeitet Dateien in Code-Ansicht oder Formular-Ansicht |
Praktischer Ablauf:
- Klicken Sie im Strukturbaum auf einen Endpunkt
- Apidog springt zur passenden Stelle in der Quelldatei
- Bearbeiten Sie YAML oder JSON direkt
- Validieren Sie die Spezifikation
- Committen und pushen Sie die Änderung
Schritt 4: Spezifikationsdateien bearbeiten
Code-Ansicht: Direkte Bearbeitung
Für YAML, JSON und Markdown verwenden Sie die Code-Ansicht. Dort bearbeiten Sie den Rohtext direkt.
Beispiel: Einen neuen Endpunkt in openapi.yaml ergänzen:
paths:
/users/{id}:
get:
summary: Benutzer nach ID abrufen
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Benutzer gefunden
"404":
description: Benutzer nicht gefunden
Apidog speichert diese Änderung in der Datei. Die Spezifikation bleibt die einzige Source of Truth.
Formular-Ansicht: Strukturierte Bearbeitung
Für unterstützte OpenAPI-Knoten können Sie in die Formular-Ansicht wechseln.
Die Formular-Ansicht hilft besonders bei:
- neuen Endpunkten mit Pflichtfeldern
- Schemas und Datenmodellen
- Sicherheitsdefinitionen
- API-Metadaten
- Beschreibungen und Beispielen
Wenn ein Knoten keine Formularbearbeitung unterstützt, bleiben Sie in der Code-Ansicht.
Schritt 5: Validieren und Vorschau anzeigen
Der Spec-first-Modus enthält Validierung und Dokumentationsvorschau direkt im Editor.
Validierung ausführen
Klicken Sie im Editor-Header auf Validierung. Apidog zeigt Warnungen und Fehler für die aktuelle Spezifikation.
Typische Probleme sind:
- YAML-/JSON-Syntaxfehler
- fehlende Pflichtfelder
- ungültige Schema-Definitionen
- fehlerhafte Referenzen
- Probleme mit Namenskonventionen
Beheben Sie diese Probleme vor dem Commit. So landen weniger Spezifikationsfehler im Pull Request.
Dokumentation prüfen
Klicken Sie auf Vorschau, um zu sehen, wie die Spezifikation als API-Dokumentation dargestellt wird.
Für Endpunkte gibt es zwei Tabs:
| Tab | Inhalt |
|---|---|
| Dokumente | Generierte Endpunkt-Dokumentation |
| Ausprobieren | Live-Anforderungs-Panel basierend auf der Endpunktdefinition |
Für Schemas und Definitionen zeigt Apidog die gerenderte Dokumentationsansicht.
Validierung und Vorschau verwenden dasselbe Seitenpanel. Wenn Sie eines öffnen, wird das andere automatisch geschlossen.
Schritt 6: Änderungen aus dem Repository abrufen
Wenn andere Teammitglieder Änderungen pushen, übernehmen Sie diese in Apidog:
- Öffnen Sie den Spezifikations-Arbeitsbereich
- Klicken Sie in der Seitenleiste auf den aktuellen Branch
- Wählen Sie Git Pull
Wenn der Webhook aktiv ist, führt Apidog die Synchronisierung bei Push-Events automatisch aus.
Empfohlener Workflow vor eigenen Änderungen:
Git Pull ausführen
↓
Spezifikation bearbeiten
↓
Validierung prüfen
↓
Vorschau kontrollieren
↓
Commit & Push
Schritt 7: Änderungen committen und pushen
Nach der Bearbeitung senden Sie Ihre Änderungen zurück an Git:
- Bearbeiten Sie Dateien im Spezifikations-Arbeitsbereich
- Öffnen Sie Änderungen in der Seitenleiste
- Prüfen Sie geänderte, hinzugefügte, umbenannte oder gelöschte Dateien
- Klicken Sie auf Commit & Push
- Wählen Sie die Dateien aus
- Schreiben Sie eine Commit-Nachricht
- Klicken Sie auf Push
Beispiel für eine sinnvolle Commit-Nachricht:
docs(api): add GET /users/{id} endpoint to OpenAPI spec
Ihre Spezifikationsänderung erscheint anschließend im normalen Pull-Request-Workflow. Reviewer können Implementierung und API-Vertrag gemeinsam prüfen.
Tipp: Verwenden Sie Alle Änderungen verwerfen, wenn Sie lokale Bearbeitungen vor dem Push zurücksetzen möchten.
Schritt 8: Mit Branches arbeiten
Der Spec-first-Modus unterstützt branch-basierte Zusammenarbeit. Apidog ordnet Git-Branches Projekt-Branches zu, sodass Sie zwischen Spezifikationsversionen wechseln können.
Häufige Branch-Operationen:
| Aktion | Vorgehen |
|---|---|
| Branch wechseln | Branch-Namen anklicken und anderen Branch auswählen |
| Bestehenden Git-Branch importieren | Neuen Branch importieren anklicken, Branch auswählen und importieren |
| Neuen Branch erstellen | Projekteinstellungen > Git & Branches > Neuer Branch |
| Synchronisierungsprobleme beheben | Neu synchronisieren in den Branch-Einstellungen verwenden |
| Synchronisierungsprotokolle anzeigen | Branch-Aktionen öffnen und Protokolle anzeigen auswählen |
Ein typischer Feature-Branch kann so aussehen:
feature/add-user-detail-endpoint
Darauf ändern Sie die Spezifikation, validieren sie, pushen sie und lassen sie im Pull Request reviewen.
Schritt 9: In CI/CD integrieren
Da Ihre Spezifikationen in Git liegen, können Sie sie wie Anwendungscode automatisiert prüfen.
Typische Pipeline-Schritte:
- Spezifikation bei jedem Pull Request linten
- Dokumentation nach Merge in
maingenerieren - API-Tests bei Spezifikationsänderungen ausführen
- Nachgelagerte Systeme synchronisieren, zum Beispiel API-Gateways, Mock-Server oder SDK-Generatoren
Beispiel für GitHub Actions:
name: Validate and Test API Spec
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint OpenAPI Spec
run: npx spectral lint openapi.yaml
- name: Run API Tests
run: apidog run tests --spec openapi.yaml
Damit laufen API-Spezifikationen durch dieselben Qualitätssicherungsschritte wie Ihr Anwendungscode.
Alternative: Speicherbasierte Projekte
Wenn Sie noch kein externes Git-Repository verbinden möchten, können Sie in Apidog speicherbasierte Spec-first-Projekte verwenden.
Diese Projekte verwenden den internen Speicher von Apidog, bieten aber weiterhin:
- dateibasierte Bearbeitung
- Validierung
- Vorschau
- Branch-Verwaltung
Die UI-Beschriftungen unterscheiden sich leicht:
| Git-basiert | Speicherbasiert |
|---|---|
| Git Pull | Synchronisieren |
| Commit & Push | Speichern |
Sie können später zu externem Git wechseln, wenn Ihr Team dafür bereit ist.
Zusammenfassung
Mit dem Spec-first-Modus verschieben Sie den API-Vertrag dorthin, wo Ihr Engineering-Workflow bereits stattfindet: nach Git.
| Vor Spec-first | Nach Spec-first |
|---|---|
| Spezifikationen liegen in separaten Tools | Spezifikationen liegen im Git-Repository |
| Export/Import zur Synchronisierung | Automatische Synchronisierung bei Push |
| Reviews passieren außerhalb von Code-Reviews | Reviews passieren in Pull Requests |
| Dokumentation wird separat generiert | Vorschau während der Bearbeitung |
| Tests sind von Spezifikationsänderungen entkoppelt | Tests können durch Spezifikationsänderungen ausgelöst werden |
Der Spec-first-Modus macht OpenAPI-Dateien zu dem Vertrag, der sie sein sollten: versioniert, überprüfbar und mit dem Code synchron.
Erstellen Sie ein Spec-first-Projekt in Apidog, verbinden Sie Ihr Repository und lassen Sie Spezifikationsänderungen durch denselben Review-Prozess laufen wie Ihren Anwendungscode.
Top comments (0)