Was ist der Apidog Spec-First Modus

Der Apidog Spec-First-Modus ist ein Beta-Arbeitsbereich für Teams, die ihre OpenAPI-Spezifikation wie Quellcode behandeln. Statt Formulare auszufüllen, bearbeiten Sie openapi.yaml oder openapi.json direkt in einem Editor im IDE-Stil und synchronisieren die Datei bidirektional mit einem verbundenen Git-Repository. Die Spezifikation ist damit die zentrale Projektquelle: bearbeiten, validieren, committen, pushen.

Probiere Apidog noch heute aus

Dieser Leitfaden zeigt, wie Sie den Spec-First-Modus praktisch einsetzen: Setup, täglicher Workflow, Git-Synchronisation, typische Bearbeitungsschritte und Einschränkungen der Beta. Für den übergeordneten Ansatz lesen Sie auch den Beitrag zum Git-nativen API-Workflow.

Was ist der Apidog Spec-First-Modus?

Der Spec-First-Modus ist ein Beta-Bearbeitungsmodus in Apidog, in dem Ihr API-Design als rohes OpenAPI-Dokument vorliegt. Sie öffnen die Datei, bearbeiten YAML oder JSON, validieren die Spezifikation und synchronisieren sie mit Git.

Der Modus ist für Teams gedacht, die bereits Git als Arbeitsgrundlage verwenden: Backend-Teams, Plattform-Teams und API-First-Organisationen, die API-Verträge in Pull Requests versionieren. Git übernimmt Historie, Reviews, Branching und Zusammenarbeit. Apidog stellt den Editor, die Validierung und die Synchronisation bereit.

Im Unterschied zu vielen API-Tools versteckt der Spec-First-Modus die Spezifikation nicht hinter Formularen. Sie arbeiten direkt an der Datei.

Spec-First-Modus vs. Design-First-Modus

Apidog bietet zwei Arbeitsweisen. Der Design-First-Modus ist visuell und formularbasiert. Der Spec-First-Modus ist codebasiert und auf Git ausgerichtet. Eine ausführlichere Gegenüberstellung finden Sie im Vergleich Spec-First vs. Design-First.

Aspekt	Design-First-Modus	Spec-First-Modus (Beta)
Primärer Editor	Visuelle Formulare und UI-Panels	YAML-/JSON-Code-Editor
Quelle der Wahrheit	Apidog-Projektdatenbank	Spezifikationsdatei im Git-Repo
Git-Synchronisation	Export/Import	Native bidirektionale Synchronisation
Geeignet für	Visuelle Designer, gemischte Teams	Git-native Engineering-Teams
Lernkurve	Geführt	Vertraut für OpenAPI-Nutzer

Keiner der Modi ist grundsätzlich besser. Wählen Sie den Modus nach Ihrem Team-Workflow.

Hauptfunktionen

OpenAPI-Editor im IDE-Stil

Im Zentrum steht ein Code-Editor für rohe OpenAPI-Dokumente. Sie bearbeiten YAML oder JSON direkt.

Der Editor unterstützt:

• Syntax-Hervorhebung
• Schema-Validierung während der Eingabe
• Autovervollständigung für OpenAPI und Swagger
• Navigation über eine automatisch erzeugte Gliederung

Beispiel für eine typische Bearbeitung:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Die Autovervollständigung ist besonders nützlich, wenn Sie tief in Schemas arbeiten und gültige OpenAPI-Felder schnell einfügen möchten.

Automatisch geparste Gliederung

Große OpenAPI-Dateien werden schnell unübersichtlich. Der Spec-First-Modus erstellt deshalb links eine navigierbare Gliederung aus Ihrer Spezifikation.

Apidog erkennt unter anderem:

• Pfade
• Operationen
• Schemas
• Komponenten

Wenn Sie auf einen Eintrag klicken, springt der Editor direkt zur passenden Stelle. Die Gliederung wird live aktualisiert, sobald sich die Datei ändert. Sie navigieren also nicht über Zeilennummern, sondern über API-Struktur: zum Beispiel POST /orders oder components.schemas.User.

Bidirektionale Git-Synchronisation

Die wichtigste Funktion ist die native Git-Synchronisation. Apidog verbindet das Spec-First-Projekt mit einem Git-Repository und hält Spezifikation und Repo in beide Richtungen synchron.

Unterstützte Verbindungen:

Anbieter	Verbindungsart
GitHub	Direkte Integration
GitLab	Direkte Integration
Azure DevOps	Über generische Git-Verbindung

Wenn Sie Änderungen aus dem Repo pullen, wird der Editor aktualisiert. Wenn Sie Ihre Bearbeitung pushen, landet die Spezifikation im verbundenen Branch.

Für GitHub gibt es zusätzlich eine separate Schritt-für-Schritt-Anleitung: OpenAPI-Spezifikation mit GitHub synchronisieren.

Commit, Push und Synchronisationsstatus

Der Workflow folgt dem bekannten Git-Modell:

1. Spezifikation bearbeiten
2. Änderungen prüfen
3. Commit-Nachricht schreiben
4. Commit erstellen
5. Zum verbundenen Branch pushen
6. Synchronisationsstatus prüfen

Die Statusanzeige zeigt, ob Ihre lokale Spezifikation mit dem Repository übereinstimmt. Wenn der Status „Gerade synchronisiert“ anzeigt, sehen Ihre Teamkollegen denselben Stand im Repo.

Dateiänderungen prüfen

Vor dem Commit zeigt der Spec-First-Modus, welche Dateien geändert, hinzugefügt oder gelöscht wurden. Dadurch können Sie prüfen, ob nur die beabsichtigten Änderungen im Commit landen.

Praktischer Ablauf:

Änderungen prüfen
→ unerwünschte Bearbeitungen verwerfen
→ Commit-Nachricht schreiben
→ committen
→ pushen

Das hilft, experimentelle Änderungen lokal zu halten, bis sie wirklich in die gemeinsame Historie gehören.

Projektbindung an Repository und Branch

Ein Spec-First-Projekt wird aus einem konkreten Repository und einem konkreten Branch erstellt, häufig main. Dadurch ist immer klar, welche Spezifikation bearbeitet wird und wohin Commits gehen.

Während der Einrichtung konfigurieren Sie außerdem Team-Berechtigungen. So legen Sie fest, wer auf das Projekt zugreifen und Änderungen vornehmen darf.

Spec-First-Modus einrichten

Die Einrichtung ist linear. Die offizielle Anleitung finden Sie in der Apidog-Dokumentation.

1. In den Spec-First-Modus wechseln

Öffnen Sie in Apidog das APIs-Modul. Unten links finden Sie den Modus-Umschalter. Wechseln Sie vom Design-First-Modus in den Spec-First-Modus.

2. Git-Anbieter verbinden

Verbinden Sie Ihren Git-Anbieter:

• GitHub direkt autorisieren
• GitLab direkt autorisieren
• Azure DevOps über generische Git-Verbindung einrichten

Für Azure DevOps verwenden Sie Standard-Git-Zugangsdaten.

3. Projekt aus Repository erstellen

Wählen Sie:

• Repository
• Branch, zum Beispiel main
• Spezifikationsdatei, zum Beispiel openapi.yaml oder openapi.json

Apidog bindet das Projekt an diese Quelle.

4. Team-Berechtigungen konfigurieren

Legen Sie fest, wer das Projekt sehen und bearbeiten darf. Stimmen Sie diese Berechtigungen möglichst mit Ihrem Git-Zugriffsmodell ab.

5. Spezifikation bearbeiten

Öffnen Sie die OpenAPI-Datei im Editor. Nutzen Sie:

• Gliederung für Navigation
• Autovervollständigung für OpenAPI-Felder
• Validierung zur Fehlererkennung

6. Änderungen prüfen und committen

Prüfen Sie die erkannten Dateiänderungen. Verwerfen Sie unerwünschte Änderungen, bevor Sie committen.

Beispiel für eine Commit-Nachricht:

Add POST /invoices endpoint

7. Zum Repository pushen

Pushen Sie den Commit in den verbundenen Branch.

8. Synchronisation prüfen

Kontrollieren Sie den Synchronisationsstatus. Wenn der Status „Gerade synchronisiert“ anzeigt, stimmen Apidog und Git-Repository überein.

Typischer täglicher Workflow

Ein praktischer Tagesablauf sieht so aus:

1. Neueste Änderungen vom verbundenen Branch pullen
2. In der Gliederung zur gewünschten Operation springen
3. YAML oder JSON bearbeiten
4. Validierungsfehler direkt beheben
5. Dateiänderungen prüfen
6. Commit erstellen
7. Push ausführen
8. Pull Request im Git-System prüfen lassen

Beispiel für eine Schema-Ergänzung:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

Der Vorteil: Die Spezifikation bleibt Code. Sie wird im selben Review- und Versionsmodell behandelt wie Ihre Anwendung.

Wer sollte den Spec-First-Modus verwenden?

Verwenden Sie den Spec-First-Modus, wenn Ihr Team:

• OpenAPI-Spezifikationen direkt als YAML oder JSON pflegt
• API-Verträge in Pull Requests reviewt
• Spezifikationen neben Service-Code versioniert
• Git als zentrale Kollaborationsplattform nutzt
• lieber im Code-Editor als in Formularen arbeitet

Wählen Sie eher den Design-First-Modus, wenn:

• Nicht-Entwickler aktiv am API-Design mitarbeiten
• Ihr Team visuelle Formulare bevorzugt
• Sie eine stärker geführte Oberfläche benötigen
• Produkt, Design und Engineering gemeinsam Endpunkte modellieren

Für die Entscheidung hilft der Vergleichsbeitrag.

Einschränkungen und Beta-Hinweise

Der Spec-First-Modus ist eine Beta-Funktion. Planen Sie entsprechend vorsichtig.

Wichtige Punkte:

• Funktionen und Verhalten können sich während der Beta ändern.
• GitHub und GitLab werden direkt unterstützt.
• Azure DevOps läuft über eine generische Git-Verbindung.
• Kritische Projekte sollten Sie erst nach einem Testlauf migrieren.
• Änderungen am verbundenen Branch sollten bewusst committed und gepusht werden.

Empfohlener Einstieg:

1. Unkritisches Repository auswählen
2. Spec-First-Projekt erstellen
3. Kleine Änderung an der Spezifikation durchführen
4. Commit und Push testen
5. Pull/Sync-Verhalten mit dem Team prüfen
6. Erst danach größere Workflows umstellen

Da die Spezifikation mit einem Live-Repository verbunden ist, gelten die üblichen Git-Regeln: sauber committen, Änderungen prüfen und Experimente bei Bedarf verwerfen.

FAQ

Ist der Spec-First-Modus kostenlos?

Der Spec-First-Modus ist eine Beta-Funktion innerhalb von Apidog. Der Zugriff hängt von Ihrem Apidog-Plan und dem Beta-Status ab. Prüfen Sie im APIs-Modul, ob der Modus für Ihr Konto verfügbar ist.

Welche Git-Anbieter werden unterstützt?

GitHub und GitLab werden direkt unterstützt. Azure DevOps funktioniert über eine generische Git-Verbindung mit Standard-Git-Zugangsdaten. Andere Git-Hosts können über diese generische Verbindung ebenfalls funktionieren, sofern sie Standard-Git unterstützen.

Kann ich zum Design-First-Modus zurückwechseln?

Ja. Der Modus-Umschalter befindet sich unten links im APIs-Modul. Sie können zwischen Spec-First- und Design-First-Modus wechseln.

Welche Dateiformate kann ich bearbeiten?

Sie bearbeiten OpenAPI-Dokumente als YAML oder JSON. Der Editor unterstützt Syntax-Hervorhebung, Schema-Validierung und Autovervollständigung für OpenAPI und Swagger.

Was passiert mit ungespeicherten Bearbeitungen?

Ungespeicherte Bearbeitungen bleiben lokal, bis Sie sie committen und pushen. Der Spec-First-Modus verfolgt Änderungen als modifiziert, hinzugefügt oder gelöscht. Wenn Sie eine Änderung nicht übernehmen möchten, verwerfen Sie sie vor dem Push.

Fazit

Der Apidog Spec-First-Modus kombiniert OpenAPI-Bearbeitung und Git-Workflow in einem Arbeitsbereich. Sie bearbeiten openapi.yaml oder openapi.json direkt, navigieren über eine automatisch erzeugte Gliederung, validieren während der Eingabe und synchronisieren bidirektional mit GitHub, GitLab oder Azure DevOps.

Der Modus ist besonders geeignet für Git-native Teams, die API-Spezifikationen wie Quellcode behandeln. Wenn das zu Ihrem Workflow passt, starten Sie mit einem kleinen Test: Repo verbinden, Spezifikation bearbeiten, committen, pushen und Synchronisationsstatus prüfen. Weitere Details finden Sie in den Docs zum Spec-First-Modus.