Git-native Kollaboration für API-Tests und Engineering

Ihre OpenAPI-Spezifikation ist der Vertrag zwischen Ihrer API und ihren Konsumenten. Aber wo befindet sich dieser Vertrag?

Allzu oft befinden sich API-Spezifikationen in isolierten Tools – einmal exportiert, vergessen und selten aktualisiert, wenn sich die Implementierung ändert. Die Dokumentation driftet ab. Testsammlungen weichen voneinander ab. Prüfer genehmigen Codeänderungen, ohne jemals die entsprechenden Spezifikationsaktualisierungen zu sehen.

Spec-first-Modus kehrt dieses Modell um. Ihre OpenAPI- oder Swagger-Dateien werden zur Quelle der Wahrheit und werden direkt in Ihrem Git-Repository zusammen mit dem Implementierungscode gespeichert. Jede Spezifikationsänderung durchläuft dieselben Branches, Pull Requests und denselben Überprüfungsprozess, den Sie bereits verwenden. API-Design, Tests und Dokumentation bleiben alle automatisch synchronisiert.

In diesem Tutorial führe ich Sie durch die Einrichtung eines Spec-first-Projekts in Apidog, das Bearbeiten von Spezifikationen mit Ihrem Team und das Synchronisieren von allem mit Ihrem Git-Workflow.

Was ist der Spec-first-Modus?

In einem typischen API-Projekt erstellen Sie Endpunkte über visuelle Formulare oder importieren bestehende Spezifikationen als Ausgangspunkt. Das Tool speichert API-Definitionen intern, und die Git-Integration (falls vorhanden) ist ein Exportschritt.

Der Spec-first-Modus ist anders. Der primäre Arbeitsbereich ist dateibasiert:

• openapi.yaml oder openapi.json leben in Ihrem Repo
• Apidog parst diese Dateien und generiert eine navigierbare API-Struktur
• Sie bearbeiten die Dateien direkt (oder über unterstützte Formulare)
• Änderungen werden automatisch mit Git synchronisiert

Die Spezifikationsdatei ist immer maßgebend. Apidog liest daraus, schreibt hinein und hält sie mit Ihrem Repository synchron.

Voraussetzungen

Um mitzumachen, benötigen Sie:

• Ein Apidog-Konto (die kostenlose Version funktioniert)
• Ein Git-Repository mit einer OpenAPI/Swagger-Datei oder ein leeres Repo für einen Neuanfang
• Schreibzugriff auf das Repository
• Grundlegende Vertrautheit mit der OpenAPI- oder Swagger-Syntax

Schritt 1: Ein Spec-first-Projekt erstellen

Klicken Sie in Apidog auf + Neues Projekt und wählen Sie Spec-first-Modus als Projekttyp.

Verbinden Sie als Nächstes Ihren Git-Anbieter:

1. Wählen Sie Ihren Anbieter (GitHub, GitLab, Azure DevOps oder Bitbucket)
2. Wählen Sie eine Organisation oder einen Arbeitsbereich
3. Wählen Sie ein bestehendes Repository aus oder erstellen Sie ein neues
4. Wählen Sie den Haupt-Branch für die Synchronisierung

Apidog synchronisiert sich mit dem Standard-Branch Ihres Repositories. Wenn dieser nicht main genannt wird, passt sich Apidog automatisch an.

Schritt 2: Webhook-Synchronisierung konfigurieren (empfohlen)

Während der Einrichtung sehen Sie eine Option zur Installation eines Webhooks. Dies ermöglicht die automatische Synchronisierung, wann immer Ihr Team in das Repository pusht.

Hinweis: Die Webhook-Installation erfordert in der Regel Administratorberechtigungen für das Repository. Wenn Sie keinen Administratorzugriff haben, überspringen Sie diesen Schritt – Sie können immer noch manuell mit Git Pull synchronisieren.

Vorteile des Webhooks:

• Team pusht Änderungen → Apidog synchronisiert automatisch
• Keine manuelle Aktualisierung erforderlich
• Jeder sieht den neuesten Spezifikationsstatus

Wenn Sie die Webhook-Einrichtung ursprünglich übersprungen haben, können Sie sie später unter Projekteinstellungen > Git & Branches hinzufügen.

Schritt 3: Den Spezifikations-Arbeitsbereich erkunden

Nach der Erstellung öffnet Ihr Projekt den Spezifikations-Arbeitsbereich – die zentrale Anlaufstelle für dateibasierte Bearbeitung und Git-Operationen.

Drei Panels arbeiten zusammen:

Klicken Sie auf einen Endpunkt im Strukturbaum → Apidog hebt den entsprechenden Abschnitt in Ihrer Quelldatei hervor. Navigieren Sie von der übergeordneten API-Ansicht zu untergeordnetem YAML, ohne Tabs wechseln zu müssen.

Schritt 4: Ihre Spezifikationsdateien bearbeiten

Code-Ansicht: Direkte Bearbeitung

Für die meisten Dateien – YAML, JSON, Markdown – verwenden Sie die Code-Ansicht, um den Rohtext zu bearbeiten.

Ihre Bearbeitungen bleiben in der Datei. Apidog transformiert oder speichert sie nicht separat. Die Spezifikationsdatei bleibt die einzige Quelle der Wahrheit.

Formular-Ansicht: Strukturierte Bearbeitung

Für unterstützte OpenAPI-Knoten – Endpunkte, Schemas, Definitionen und API-Übersicht – wechseln Sie zur Formular-Ansicht.

Die Formular-Ansicht ist nützlich, wenn:

• Endpunkte mit allen erforderlichen Feldern hinzugefügt werden, ohne die YAML-Struktur auswendig lernen zu müssen
• Schemas visuell bearbeitet werden
• Sicherheitsdefinitionen und API-Metadaten aktualisiert werden

Wenn ein Knoten die Formularbearbeitung nicht unterstützt, bleiben Sie in der Code-Ansicht.

Schritt 5: Sofort validieren und Vorschau anzeigen

Der Spec-first-Modus beinhaltet Echtzeit-Validierung und Dokumentationsvorschau – keine externen Tools erforderlich.

Probleme mit der Validierung prüfen

Klicken Sie im Editor-Header auf Validierung. Ein Panel zeigt alle Warnungen und Fehler in Ihrer aktuellen Spezifikation an.

Das Abzeichen zeigt die Gesamtzahl der Probleme an. Erfassen Sie:

• Syntaxfehler
• Fehlende Pflichtfelder
• Schemaverletzungen
• Probleme mit Namenskonventionen

Beheben Sie Probleme vor dem Commit. Die Prüfer Ihres Teams müssen diese nicht manuell erkennen.

Vorschau Ihrer Dokumentation

Klicken Sie auf Vorschau, um zu sehen, wie Ihre Spezifikation als API-Dokumentation dargestellt wird.

Für Endpunkte enthält die Vorschau zwei Tabs:

Für Schemas und Definitionen zeigt die Vorschau die gerenderte Dokumentationsansicht.

Validierung und Vorschau teilen sich dasselbe Seitenpanel. Das Öffnen eines Panels schließt das andere automatisch.

Schritt 6: Updates von Ihrem Team abrufen

Wenn Mitarbeiter Änderungen in Ihr Repository pushen, übernehmen Sie diese in Apidog:

1. Öffnen Sie den Spezifikations-Arbeitsbereich
2. Klicken Sie in der Seitenleiste auf den Namen des aktuellen Branches
3. Wählen Sie Git Pull

Wenn die Webhook-Synchronisierung aktiv ist, ruft Apidog bei Repository-Push-Ereignissen automatisch ab – kein manueller Schritt erforderlich.

Schritt 7: Ihre Änderungen committen und pushen

Nachdem Sie Dateien in Apidog bearbeitet haben, senden Sie Ihre Updates zurück an Git:

1. Nehmen Sie Änderungen im Spezifikations-Arbeitsbereich vor
2. Klicken Sie in der Seitenleiste auf Änderungen, um geänderte, hinzugefügte, umbenannte und gelöschte Dateien anzuzeigen
3. Klicken Sie auf Commit & Push
4. Wählen Sie aus, welche Dateien einbezogen werden sollen
5. Schreiben Sie eine Commit-Nachricht
6. Klicken Sie auf Push

Ihre Spezifikationsaktualisierungen erscheinen nun im selben Pull-Request-Workflow wie Ihre Codeänderungen. Teammitglieder können die Implementierung und den API-Vertrag an einem Ort überprüfen, kommentieren und genehmigen.

Tipp: Verwenden Sie Alle Änderungen verwerfen, wenn Sie lokale Bearbeitungen vor dem Pushen aufgeben möchten.

Schritt 8: Mit Branches arbeiten

Der Spec-first-Modus unterstützt die vollständige branch-basierte Zusammenarbeit. Apidog ordnet Git-Branches Projekt-Branches zu, sodass Sie zwischen Spezifikationsversionen wechseln können.

Häufige Branch-Operationen

Die Branch-Verwaltung funktioniert genauso, wie Sie es von Git erwarten – Feature-Branches, Releases und parallele Entwicklung werden alle korrekt synchronisiert.

Schritt 9: Integration mit CI/CD

Da Ihre Spezifikationen in Git leben, passen sie natürlich in Automatisierungspipelines:

• Spezifikationen bei jedem PR linten mit Apidog-Validierung oder Tools wie Spectral
• Dokumentation automatisch generieren, wenn Spezifikationen mit Main zusammengeführt werden
• API-Tests ausführen, die durch Spezifikationsänderungen ausgelöst werden
• Synchronisierung mit nachgelagerten Systemen – API-Gateways, Mock-Server, SDK-Generatoren

Beispiel GitHub Actions Workflow:

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

Ihre API-Spezifikationen durchlaufen nun dieselben Qualitätssicherungsschritte wie Ihr Anwendungscode.

Alternative: Speicherbasierte Projekte

Wenn Sie noch nicht bereit sind, ein externes Git-Repository zu verbinden, bietet Apidog speicherbasierte Spec-first-Projekte an.

Diese Projekte verwenden den internen Speicher von Apidog, bieten aber weiterhin:

• Dateibasierte Bearbeitung
• Validierung und Vorschau
• Branch-Verwaltung

UI-Beschriftungen passen sich leicht an:

• Git Pull wird zu Synchronisieren
• Commit & Push wird zu Speichern

Migrieren Sie zu externem Git, wann immer Ihr Team bereit ist.

Zusammenfassung

Mit dem Spec-first-Modus wird Ihr API-Workflow zu:

Der Spec-first-Modus macht OpenAPI-Dateien zu dem Vertrag, der sie sein sollten – versioniert, überprüft und immer auf Ihren Code abgestimmt.

Bereit zum Ausprobieren? Erstellen Sie ein Spec-first-Projekt in Apidog und verbinden Sie Ihr erstes Repository.