DEV Community

Cover image for Apidog Spec-First: Visuelles Design ist nicht mehr alleiniger Fokus
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Apidog Spec-First: Visuelles Design ist nicht mehr alleiniger Fokus

In jedem API-Team, mit dem ich gearbeitet habe, gibt es zwei Lager.

Teste Apidog noch heute

Die einen schreiben ihre OpenAPI-Spezifikation von Hand, committen sie in ein specs/-Verzeichnis und behandeln Git als Source of Truth. Die anderen arbeiten im visuellen Designer, exportieren die Spezifikation bei Bedarf und bereinigen später die Unterschiede zwischen UI und Repository.

Ich habe beides gemacht. Manuelles OpenAPI ist am ersten Tag langsamer, aber ab Tag neunzig oft schneller. Visuelle Designer sind umgekehrt: schneller beim Einstieg, schwieriger bei langfristiger Konsistenz. Apidog war bisher vor allem stark im zweiten Modell. Der visuelle Designer ist gut, aber der YAML-Roundtrip war etwas, das man im Review erklären musste.

Seit Mitte April gibt es den Spec-First Modus (Beta) im Dialog für neue Projekte. Ich habe ihn nicht direkt am Starttag bewertet, sondern mit einer echten OpenAPI-Spezifikation aus einem Nebenprojekt ausprobiert. Dieser Artikel zeigt, wie der Modus funktioniert, wie Sie ihn einrichten und für welche Teams er sinnvoll ist.

Was der Spec-First Modus ändert

Apidog hat jetzt zwei Projektmodi, die sich konzeptionell deutlich unterscheiden.

Im Standardmodus erstellen Sie Endpunkte über visuelle Formulare. Apidog generiert daraus im Hintergrund eine OpenAPI-Spezifikation. Das ist sinnvoll, wenn Ihr Team noch nicht regelmäßig YAML oder JSON schreibt.

Im Spec-First Modus ist die Spezifikation selbst das zentrale Artefakt. Sie arbeiten direkt an .yaml- oder .json-Dateien. Dazu kommen:

  • ein Code-Editor für OpenAPI-Dateien
  • Syntaxhervorhebung
  • schema-basierte Autovervollständigung
  • automatische Pfad- und Endpunkt-Gliederung
  • bidirektionale Synchronisation mit einem Git-Repository

Der wichtigste Unterschied: Die Datei im Repository ist die Wahrheit. Die UI ist nur eine Arbeitsoberfläche dafür.

Der Arbeitsbereich des Spec-First Modus, mitten in der Bearbeitung eines Pet-Store-Projekts. Die linke Seitenleiste ist die automatisch generierte Pfadgliederung – beachten Sie oben die Pfade (224), dann einzelne Routen wie /store/auth/{email}, /admin/auth, /store/token, die direkt aus der Datei entstehen. Oben rechts: die Anzeige Änderungen (1) und der grüne Commit & Push-Button. Unten links: Gerade synchronisiert – die Synchronisierungsstatusanzeige, auf die der Text später verweist.

Gerade die Gliederungsansicht ist praktisch: YAML versteckt Struktur leicht in langen Dateien. Apidog rendert daraus während des Tippens eine navigierbare Seitenleiste. Sie schreiben weiter in der Spezifikation, bekommen aber Navigation wie in einem visuellen Tool.

Projekt im Spec-First Modus einrichten

Der Ablauf ist kurz. In meinem Test dauerte die Einrichtung weniger als zehn Minuten, inklusive Git-Autorisierung.

1. Neues Projekt im richtigen Modus erstellen

Öffnen Sie den Projektbildschirm und wählen Sie:

+ Neues Projekt → Allgemein → Spec-First Modus
Enter fullscreen mode Exit fullscreen mode

Achten Sie auf die Modusauswahl. Der Allgemeine Modus ist als „Empfohlen“ markiert, deshalb übersieht man die Spec-First-Kachel leicht.

2. Git-Repository verbinden

Scrollen Sie im Dialog zu Mit Git-Repository verbinden und autorisieren Sie Ihren Git-Anbieter.

Danach wählen Sie:

  • Organisation
  • Repository
  • Main Branch

In meinem Test habe ich GitHub verwendet. Apidog synchronisiert anschließend die OpenAPI-Dateien aus diesem Branch in den Arbeitsbereich.

3. Projekt konfigurieren

Legen Sie fest:

  • Projektname
  • Team-Berechtigungen
  • verbundenes Repository
  • Ziel-Branch

Klicken Sie dann auf Erstellen. Beim ersten Sync zieht Apidog alle vorhandenen .yaml- und .json-Dateien aus dem Repository.

Die Schritte 1–3 finden im selben Dialog statt. Oben: die beiden Modus-Kacheln. Der Allgemeine Modus ist als Empfohlen gekennzeichnet, was dazu führt, dass die Kachel des Spec-First Modus (rechts, Beta-Abzeichen, violette Hervorhebung) leicht übersehen wird. Die Spec-First-Kachel listet auf, was sich darunter ändert: OpenAPI Spec Editor (unterstützt Visualisierung) und bidirektionale Synchronisation mit dem Git-Repository. Unten: das Panel 'Mit Git-Repository verbinden' mit Dropdowns für Organisation, Repository (Pet-Store) und Main Branch (main) sowie das Feld Projektname. Ein Bildschirm, drei Entscheidungen.

OpenAPI-Dateien bearbeiten

Öffnen Sie eine YAML- oder JSON-Datei im Projekt. Der Editor verhält sich eher wie eine IDE als wie ein Formular.

Beispiel für eine einfache OpenAPI-Struktur:

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0

paths:
  /pets:
    get:
      summary: List pets
      responses:
        "200":
          description: Successful response
Enter fullscreen mode Exit fullscreen mode

Während Sie paths, Methoden oder Schemas ergänzen, aktualisiert Apidog die Seitenleiste automatisch. Ein Klick auf einen Endpunkt springt zur passenden Stelle in der Datei.

Wenn Sie bereits mit VS Code und einer OpenAPI-Erweiterung arbeiten, fühlt sich das vertraut an. Der Unterschied ist, dass Git-Sync, Navigation und Apidog-Arbeitsbereich direkt zusammenhängen.

Änderungen committen und pushen

Wenn Sie die Spezifikation geändert haben:

  1. Klicken Sie oben rechts auf Commit & Push.
  2. Prüfen Sie die Liste unter Änderungen.
  3. Schreiben Sie eine Commit-Nachricht.
  4. Klicken Sie auf Pushen.

Es gibt keinen separaten Staging-Schritt. Alles, was im Dialog unter Änderungen steht, wird Teil des Commits.

Der Dialog zum Pushen ins Git-Repository. Beachten Sie die Struktur: ein Feld für die Commit-Nachricht, eine Liste der Änderungen (1 Datei) mit einem Kontrollkästchen pro Datei und drei Schaltflächen unten – Alle Änderungen verwerfen (links, destruktiv), Abbrechen (neutral), und Pushen (die primäre Aktion, lila). Im Hintergrund sehen Sie den Commit & Push-Button oben rechts im Arbeitsbereich, der diesen Dialog geöffnet hat.

Ein typischer Commit könnte so aussehen:

Add store authentication endpoints
Enter fullscreen mode Exit fullscreen mode

Für reine Spezifikationsänderungen ist diese Vereinfachung sinnvoll. Wenn Sie komplexere Git-Flows mit selektivem Staging brauchen, sollten Sie prüfen, ob der Apidog-Workflow zu Ihrem Team passt.

Synchronisationsstatus beobachten

Unten links zeigt Apidog den Sync-Status an, zum Beispiel Gerade synchronisiert.

Diese Anzeige ist wichtig, weil sie Ihnen sagt, ob:

  • lokale Änderungen noch nicht gepusht wurden
  • Remote-Änderungen vorliegen
  • Arbeitsbereich und Repository synchron sind

In meinem Test war diese Anzeige zuverlässiger als das ständige Öffnen von Dialogen. Wenn sie grün ist, stimmen Arbeitsbereich und Repository überein.

Verhalten bei externen Git-Änderungen

Ich habe dieselbe Datei lokal bearbeitet und per Terminal gepusht, während Apidog geöffnet war.

Ablauf:

git checkout main
git pull
# OpenAPI-Datei bearbeiten
git add openapi.yaml
git commit -m "Update auth schema"
git push
Enter fullscreen mode Exit fullscreen mode

Apidog erkannte anschließend, dass Remote-Änderungen vorhanden waren. Die Synchronisationsanzeige wechselte entsprechend, und ein Klick zog die Änderungen in den Editor.

Das ist der zentrale Vorteil des Modus: Ein Teammitglied kann weiter mit Vim, VS Code oder JetBrains arbeiten, während andere Apidog verwenden. Entscheidend ist nur die Datei im Repository.

Was im Spec-First Modus aktuell zu beachten ist

Der Modus ist bewusst anders aufgebaut als der visuelle Standardmodus.

Wichtig: Ein Projekt lässt sich nicht einfach später vom Spec-First Modus zurück in den visuellen Designer umschalten. Die zugrunde liegenden Datenmodelle unterscheiden sich.

Wenn Ihr Team beide Arbeitsweisen parallel braucht, ist ein praktikabler Workflow:

  1. OpenAPI-Spezifikation in einem Git-Repository pflegen.
  2. Ein Apidog-Projekt im Spec-First Modus mit diesem Repository verbinden.
  3. Für visuelle Nutzer ein separates Projekt aus derselben Spezifikation importieren.

Das ist nicht komplett nahtlos, aber nachvollziehbar, solange die Spezifikation in Git die gemeinsame Quelle bleibt.

Wann der Spec-First Modus passt

Der Modus ist sinnvoll, wenn Ihr Team bereits spec-first arbeitet oder dorthin wechseln möchte.

Typische Voraussetzungen:

  • OpenAPI-Dateien liegen bereits in Git.
  • CI prüft die Spezifikation, zum Beispiel mit spectral lint.
  • Client-SDKs oder Server-Stubs werden aus der Spezifikation generiert.
  • Pull Requests gegen YAML- oder JSON-Dateien sind normal.
  • Das Team will Drift zwischen Apidog und Repository vermeiden.

Ein möglicher CI-Schritt sieht zum Beispiel so aus:

name: lint-openapi

on:
  pull_request:
    paths:
      - "openapi/**/*.yaml"
      - "openapi/**/*.json"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi/**/*.yaml
Enter fullscreen mode Exit fullscreen mode

Wenn Ihr Repository so oder ähnlich aufgebaut ist, passt der Spec-First Modus gut.

Wann der Standardmodus besser ist

Der Spec-First Modus ist nicht für jedes Team die bessere Wahl.

Bleiben Sie eher beim Standardmodus, wenn:

  • Ihr Team noch keine OpenAPI-Erfahrung hat.
  • Nicht-technische Teammitglieder Endpunkte pflegen.
  • Der visuelle Designer der Hauptgrund ist, warum Personen beitragen können.
  • Sie Formulare statt YAML-Strukturen bevorzugen.
  • Sie beide Modi zwingend in einem einzigen Projekt mischen müssen.

Spec-first tauscht einfache Einarbeitung gegen mehr Kontrolle über das Artefakt. Dieser Tausch lohnt sich nicht, wenn die meisten Beitragenden keine API-Spezialisten sind.

Praktischer Entscheidungsrahmen

Verwenden Sie den Spec-First Modus, wenn diese Aussage stimmt:

Die OpenAPI-Datei im Repository muss immer die Wahrheit sein.
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie den Standardmodus, wenn diese Aussage wichtiger ist:

Das Team muss APIs möglichst einfach über eine visuelle Oberfläche pflegen können.
Enter fullscreen mode Exit fullscreen mode

Beide Workflows sind legitim. Der entscheidende Punkt ist, welches Artefakt Ihr Team als führend betrachtet: die Datei oder die UI.

Fazit

Spec-First-Entwicklung bedeutete lange, auf API-Design-Tools zu verzichten. Entweder lebte man in YAML und gab Komfortfunktionen auf, oder man arbeitete im visuellen Designer und akzeptierte Drift zum Repository.

Der Spec-First Modus von Apidog schließt diese Lücke besser als der bisherige Workflow: Die Datei im Repository ist die Datei im Editor. Die Gliederung ist nur eine Ansicht. Die Git-Synchronisation ist der zentrale Mechanismus.

Wenn Ihr Team OpenAPI bereits in Git pflegt, lohnt sich ein Test. Erstellen Sie ein neues Projekt im Spec-First Modus, verbinden Sie ein Repository, ändern Sie eine Spezifikation und pushen Sie den ersten Commit. Die Einrichtung dauert etwa zehn Minuten. Ob der Workflow dauerhaft passt, zeigt sich nach einigen Tagen realer Arbeit.

Top comments (0)