Spec-First oder Design-First: Welcher Apidog Modus ist besser für dich?

Das API-Modul von Apidog bietet zwei Workflows, um denselben API-Vertrag zu erstellen: Design-First über visuelle Formulare oder Spec-First über einen YAML/JSON-Editor mit Git-Synchronisierung. Beide Wege erzeugen gültiges OpenAPI. Entscheidend ist, wie Ihr Team im Alltag arbeitet: klickbasiert und geführt oder codebasiert und Git-nativ.

Teste Apidog noch heute

In diesem Leitfaden vergleichen wir beide Modi praktisch: Wann Sie welchen Modus verwenden, wie Git ins Spiel kommt und wie Sie zwischen den Modi wechseln. Der Umschalter befindet sich unten links im API-Modul. Sie legen also keine endgültige Entscheidung fest, sondern wählen eine sinnvolle Standardeinstellung für Ihr Team.

Die zwei Philosophien

Beide Ansätze folgen derselben Grundregel:

Der API-Vertrag wird definiert, bevor die Implementierung geschrieben wird.

Der Vertrag ist die Quelle der Wahrheit. Daraus entstehen später Code, Tests, Mocks und Dokumentation.

Design-First

Im Design-First-Modus erstellen Sie den Vertrag über eine strukturierte Oberfläche:

• HTTP-Methode auswählen
• Pfad definieren
• Query- und Path-Parameter hinzufügen
• Request- und Response-Schemas über einen Baum-Editor modellieren
• Beispiele ergänzen

Apidog generiert daraus die zugrunde liegende OpenAPI-Spezifikation.

Spec-First

Im Spec-First-Modus schreiben Sie die Spezifikation direkt als Datei:

openapi: 3.0.3
info:
  title: Beispiel API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Benutzer abrufen
      responses:
        "200":
          description: Erfolgreiche Antwort

Die OpenAPI- oder Swagger-Datei ist Ihre Arbeitsfläche. Sie bearbeiten sie wie Quellcode.

In der Praxis überschneiden sich die Begriffe. „Spec-First“ und „Contract-First“ werden oft synonym verwendet. Für Apidog ist die Unterscheidung konkret:

• Design-First: Sie arbeiten mit Formularen.
• Spec-First: Sie arbeiten direkt im Texteditor.

Beide unterscheiden sich von Code-First. Bei Code-First entsteht die Spezifikation aus Annotationen oder Implementierungscode. In beiden Apidog-Modi steht der Vertrag dagegen vor dem Code. Mehr Kontext dazu finden Sie im Überblick zum Git-nativen API-Workflow.

Apidog Design-First-Modus

Der Design-First-Modus ist der visuelle API-Designer. Er eignet sich besonders, wenn Sie schnell eine API-Struktur erstellen wollen, ohne die OpenAPI-Syntax manuell zu schreiben.

Typischer Ablauf:

1. Öffnen Sie das API-Modul.
2. Erstellen Sie einen neuen Endpunkt.
3. Wählen Sie die HTTP-Methode, z. B. GET, POST oder PATCH.
4. Definieren Sie den Pfad, z. B. /users/{id}.
5. Ergänzen Sie Parameter, Header und Request Body.
6. Modellieren Sie Response-Schemas.
7. Fügen Sie Beispiele hinzu.
8. Nutzen Sie den Vertrag anschließend für Mocks, Tests oder Dokumentation.

Der wichtigste Vorteil: Sie müssen sich die OpenAPI-Struktur nicht merken. Der Editor führt Sie durch gültige Eingaben und reduziert Syntaxfehler.

Beispiel: Statt manuell ein Schema zu schreiben, definieren Sie Felder über den Schema-Baum:

{
  "id": "string",
  "email": "string",
  "name": "string"
}

Wiederverwendbare Komponenten wie ein gemeinsames Error-Schema oder ein Standard-Header lassen sich ebenfalls direkt über die Oberfläche anlegen.

Der Design-First-Modus unterstützt Branches innerhalb von Apidog. Dadurch können Teams parallel an API-Varianten arbeiten und Änderungen später zusammenführen. Reviews erfolgen über strukturierte Diffs statt über reine YAML-Zeilenvergleiche. Das ist hilfreich, wenn nicht alle Beteiligten täglich mit OpenAPI arbeiten.

Der Nachteil: Sie arbeiten durch eine Abstraktion. Wenn Sie OpenAPI bereits sehr gut kennen, können die Formulare langsamer wirken als das direkte Schreiben der Spezifikation.

Apidog Spec-First-Modus

Der Spec-First-Modus befindet sich derzeit in der Beta-Phase. Statt Formularen verwenden Sie einen IDE-ähnlichen Editor und schreiben OpenAPI oder Swagger direkt in YAML oder JSON.

Dieser Modus passt zu Teams, die ihre API-Spezifikation wie Quellcode behandeln möchten.

Der Editor unterstützt:

• Syntax-Hervorhebung
• Inline-Validierung
• Auto-Vervollständigung für OpenAPI- und Swagger-Schemas
• automatische Gliederung von Pfaden und Komponenten
• Synchronisierungsstatus zum verbundenen Git-Repository

Ein einfaches Beispiel für einen Endpunkt:

paths:
  /users/{id}:
    get:
      summary: Benutzer nach ID abrufen
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Benutzer gefunden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Benutzer nicht gefunden

Der zentrale Punkt ist die bidirektionale Git-Synchronisierung.

Sie können ein Repository verbinden, zum Beispiel:

• GitHub
• GitLab
• Azure DevOps über eine generische Git-Verbindung

Danach sind zwei Workflows möglich:

Workflow 1: In Apidog bearbeiten

1. Spezifikation in Apidog ändern.
2. Validierung prüfen.
3. Änderungen committen.
4. Änderungen aus Apidog pushen.
5. Pull Request oder Review im Git-System durchführen.

Workflow 2: Im Code-Editor bearbeiten

1. OpenAPI-Datei lokal im Editor ändern.
2. Änderungen committen und pushen.
3. Änderungen zurück nach Apidog synchronisieren.
4. API in Apidog weiter für Mocking, Tests oder Dokumentation nutzen.

Die vollständige Einrichtung ist in den Spec-First-Modus-Dokumenten beschrieben.

Dieser Modus behandelt den API-Vertrag wie jedes andere Code-Artefakt: versioniert, reviewbar und in Git nachvollziehbar. Wenn Ihr Team Spezifikationen bereits als Code verwaltet, lesen Sie ergänzend den Beitrag zur API-Spezifikation als Code.

Gegenüberstellung

Beide Modi erzeugen gültiges OpenAPI und können für Mocking, Tests und Dokumentation genutzt werden. Der Unterschied liegt im Editor und im Git-Workflow.

Bereich	Design-First-Modus	Spec-First-Modus (Beta)
Editor	Visuelle Formulare und Schema-Baum	IDE-ähnlicher YAML/JSON-Code-Editor
Spezifikationsformat	OpenAPI wird generiert	OpenAPI / Swagger wird manuell geschrieben
Git-Workflow	Branch-Unterstützung innerhalb von Apidog	Bidirektionale Synchronisierung mit GitHub, GitLab und Azure DevOps über Git-Verbindung
Validierung	Durch Formularstruktur erzwungen	Inline-Syntaxprüfung und Auto-Vervollständigung
Navigation	Endpunktliste und Ordner	Automatisch geparste Gliederung in der linken Seitenleiste
Lernkurve	Niedrig	Höher, OpenAPI-Kenntnisse erforderlich
Geeignet für	Gemischte Teams, schnelles Onboarding	Engineering-Teams, die Spezifikationen als Code behandeln

Welchen Modus sollten Sie wählen?

Verwenden Sie Design-First, wenn ...

• nicht alle Beteiligten OpenAPI-Syntax kennen
• Produkt, QA und Engineering gemeinsam am Vertrag arbeiten
• Sie schnell neue Endpunkte entwerfen möchten
• strukturierte Reviews wichtiger sind als Zeilen-Diffs
• Sie eine neue API von Grund auf modellieren

Praktisches Beispiel:

Ein Team entwirft eine neue Checkout-API. Product definiert fachliche Anforderungen, QA prüft Statuscodes und Backend ergänzt Schemas. In diesem Fall ist Design-First sinnvoll, weil alle Beteiligten ohne YAML-Kenntnisse mitarbeiten können.

Verwenden Sie Spec-First, wenn ...

• Ihre OpenAPI-Datei bereits im Repository liegt
• API-Änderungen über Pull Requests reviewed werden
• Sie Spec-Linting in CI verwenden
• Sie eine zentrale YAML- oder JSON-Datei als kanonische Quelle nutzen
• Backend-Teams direkt an der Spezifikation arbeiten

Praktisches Beispiel:

Ein Backend-Team verwaltet openapi.yaml neben dem Service-Code. Jede API-Änderung läuft über Pull Requests, CI prüft die Spezifikation, und nach dem Merge wird die Dokumentation aktualisiert. In diesem Fall passt Spec-First besser.

Praktischer Mittelweg

Viele Teams kombinieren beide Modi:

1. Neue Endpunkte im Design-First-Modus skizzieren.
2. Schemas und Beispiele gemeinsam validieren.
3. Wenn die API stabiler ist, in den Spec-First-Modus wechseln.
4. Die Spezifikation über Git versionieren und per Pull Request reviewen.

Die Modi sind keine konkurrierenden Produkte. Sie sind zwei Bearbeitungsansichten desselben Vertrags.

So wechseln Sie die Modi

Der Wechsel erfolgt über einen Umschalter im API-Modul.

Vorgehen:

1. Öffnen Sie Ihr Apidog-Projekt.
2. Wechseln Sie in das API-Modul.
3. Suchen Sie unten links den Modus-Umschalter.
4. Wechseln Sie zwischen Design-First und Spec-First.
5. Prüfen Sie, ob Endpunkte, Schemas und Beispiele korrekt angezeigt werden.

Wichtig beim Wechsel:

• Die zugrunde liegende Spezifikation bleibt dieselbe.
• Endpunkte, Schemas und Beispiele werden übernommen.
• Sie ändern den Editor, nicht den API-Vertrag.
• Für Git-Synchronisierung im Spec-First-Modus müssen Sie zuerst ein Repository verbinden.
• Da Spec-First aktuell Beta ist, sollten Sie den Workflow vor produktiver Nutzung in einem Testprojekt prüfen.

FAQ

Ist Spec-First dasselbe wie Contract-First?

In der Praxis ja. Beide Begriffe bedeuten, dass die API-Spezifikation vor der Implementierung erstellt wird und als Quelle der Wahrheit dient.

Der Spec-First-Modus von Apidog ist ein Contract-First-Workflow, bei dem der Vertrag eine handgeschriebene OpenAPI- oder Swagger-Datei ist, die mit Git synchronisiert wird.

Funktioniert der Spec-First-Modus mit GitLab und Azure DevOps?

Ja. Der Spec-First-Modus unterstützt bidirektionale Git-Synchronisierung mit GitHub und GitLab. Azure DevOps funktioniert über eine generische Git-Verbindung.

Kann ich ohne Datenverlust vom Design-First- zum Spec-First-Modus wechseln?

Ja. Beide Modi lesen und schreiben denselben zugrunde liegenden Vertrag. Ihre Endpunkte, Schemas und Beispiele bleiben erhalten. Sie wechseln nur die Bearbeitungsoberfläche.

Wann sollte ich nicht Spec-First verwenden?

Wenn Ihr Team wenig Erfahrung mit OpenAPI hat oder viele nicht-technische Beteiligte am API-Design mitarbeiten, ist Design-First meist der bessere Startpunkt. Spec-First lohnt sich besonders dann, wenn Git-Reviews und eine zentrale Spezifikationsdatei Teil Ihres Workflows sind.

Fazit

Wählen Sie den Modus nach Ihrem Arbeitsstil:

• Design-First, wenn Sie schnell, geführt und teamübergreifend modellieren möchten.
• Spec-First, wenn Sie OpenAPI als Code behandeln und über Git versionieren wollen.

Der API-Vertrag bleibt in beiden Fällen derselbe. Öffnen Sie das API-Modul, testen Sie den Umschalter unten links und erstellen Sie denselben Endpunkt einmal visuell und einmal als YAML. Danach sehen Sie schnell, welcher Workflow besser zu Ihrem Team passt.