Das API-Modul von Apidog bietet Ihnen zwei Wege, dasselbe zu erstellen: einen API-Vertrag. Einer verwendet visuelle Formulare. Der andere verwendet einen Rohcode-Editor, der in Git integriert ist. Beide erzeugen gültiges OpenAPI. Der Unterschied liegt in der täglichen Arbeitsweise Ihres Teams, und welche Methode besser passt, hängt weniger vom Tool als vielmehr von Ihren Gewohnheiten ab.
Dieser Leitfaden beleuchtet die Design-First- vs. Spec-First-Entscheidung in Apidog: Was jeder Modus ist, wie sie Git handhaben und welche Teams tendenziell welche wählen. Sie wechseln zwischen ihnen über einen einzigen Umschalter unten links im API-Modul, sodass die Wahl nicht dauerhaft ist. Die Wahl der richtigen Standardeinstellung spart jedoch Reibung.
Die zwei Philosophien
Vor den Modi, die Denkweise. Beide Ansätze teilen eine Regel: Sie definieren den API-Vertrag, bevor Sie die Implementierung schreiben. Der Vertrag ist die Quelle der Wahrheit. Code, Tests, Mocks und Dokumentation leiten sich alle daraus ab.
Design-First bedeutet, dass Sie diesen Vertrag über eine strukturierte Oberfläche gestalten. Sie fügen Endpunkte, Parameter und Schemas über Formulare und Dropdowns hinzu. Das Tool garantiert, dass die Ausgabe gültig ist, da Sie nur gültige Werte eingeben können.
Spec-First (oft auch Contract-First genannt) bedeutet, dass Sie den Vertrag direkt als Spezifikationsdatei schreiben: OpenAPI in YAML oder JSON. Die Spezifikation *ist* Ihre Arbeitsfläche. Sie bearbeiten sie wie Quellcode.
Diese Begriffe überschneiden sich in der Praxis. „Contract-First“ und „Spec-First“ sind nahezu Synonyme, und viele Teams verwenden „Design-First“ locker, um jeden Ansatz zu bezeichnen, bei dem der Vertrag dem Code vorausgeht. Die nützliche Unterscheidung hier ist konkret: In Apidog gibt Ihnen ein Modus Formulare, der andere einen Texteditor. Das ist die entscheidende Linie bei der Wahl.
Es ist lohnenswert, beide von der Design-First- vs. Code-First-API-Entwicklung abzugrenzen. Code-First generiert die Spezifikation *aus* Anmerkungen in Ihrer Implementierung, sodass der Code die Führung übernimmt. Beide Apidog-Modi halten den Vertrag vor dem Code. Sie unterscheiden sich lediglich darin, wie Sie ihn erstellen. Für ein umfassenderes Bild der Behandlung Ihrer Spezifikation als versioniertes Artefakt, siehe unsere Übersicht über den Git-nativen API-Workflow.
Apidog Design-First-Modus
Der Design-First-Modus ist der visuelle Designer. Sie erstellen Endpunkte über eine geführte Oberfläche: Wählen Sie eine Methode, benennen Sie den Pfad, fügen Sie Abfrage- und Pfadparameter hinzu, definieren Sie Anforderungs- und Antwortschemas über einen Baum-Editor und fügen Sie Beispiele an. Apidog rendert im Hintergrund die zugrunde liegende OpenAPI für Sie.
Dieser Modus ist der Standard für die meisten Teams, und das aus gutem Grund. Sie müssen sich die OpenAPI-Syntax nicht merken. Der Schema-Editor erzwingt die Struktur, sodass Sie keine Spezifikation mit einer falsch platzierten Klammer oder einem ungültigen Typ veröffentlichen können. Wiederverwendbare Komponenten, wie ein gemeinsames Error-Schema oder ein gemeinsamer Header, sind nur wenige Klicks entfernt.
Der Design-First-Modus unterstützt auch Branches, sodass Teams parallel an separaten Versionen des API-Designs arbeiten und diese später abgleichen können. Prüfer sehen einen strukturierten Diff statt Rohtext, was Vertragsänderungen für Personen, die nicht ständig mit YAML arbeiten, leichter lesbar macht.
Der Kompromiss: Sie arbeiten durch eine Abstraktion. Wenn Sie bereits in OpenAPI denken, können sich die Formulare wie zusätzliche Klicks zwischen Ihnen und der Spezifikation anfühlen, die Sie im Kopf haben.
Apidog Spec-First-Modus
Der Spec-First-Modus, derzeit in der Beta-Phase, kehrt dies um. Statt Formularen erhalten Sie einen IDE-ähnlichen Code-Editor und schreiben die OpenAPI- oder Swagger-Spezifikation direkt in YAML oder JSON. Er ist für Teams konzipiert, die ihre API-Definition wie jede andere Quelldatei in Git haben möchten.
Der Editor verhält sich wie der in Ihrem Code-Editor: Syntax-Hervorhebung, Inline-Validierung und Auto-Vervollständigung, die auf die OpenAPI- und Swagger-Schemas abgestimmt sind. Während Sie tippen, analysiert eine linke Seitenleiste Ihre Spezifikation automatisch in eine Gliederung von Pfaden und Komponenten, sodass Sie eine große Datei ohne Scrollen navigieren können. Ein Synchronisierungsindikator zeigt an, ob Ihre lokalen Änderungen mit dem verbundenen Repository übereinstimmen.
Das Hauptelement ist die bidirektionale Git-Synchronisierung. Sie verbinden ein Repository auf GitHub oder GitLab (Azure DevOps funktioniert über eine generische Git-Verbindung), und Apidog synchronisiert Ihre Spezifikationsdatei in beide Richtungen. Bearbeiten Sie in Apidog, dann committen und pushen Sie direkt aus der App. Oder bearbeiten Sie die Spezifikation in Ihrem Code-Editor, pushen Sie von dort und ziehen Sie die Änderungen zurück in Apidog. Die Spezifikationsdatei ist die gemeinsame Wahrheit, und beide Oberflächen bleiben synchron. Die vollständige Einrichtung können Sie in den Spec-First-Modus-Dokumenten nachlesen.
Dieser Modus behandelt Ihren API-Vertrag so, wie Sie jedes andere Code-Artefakt behandeln würden: in Pull Requests überprüft, neben den Diensten versioniert, die ihn implementieren, und Zeile für Zeile verglichen. Wenn Ihr Team Infrastruktur und Konfiguration bereits so verwaltet, lesen Sie unsere vertiefende Betrachtung zum Thema API-Spezifikation als Code für die dahinterstehende Begründung.
Gegenüberstellung
Beide Modi erzeugen dasselbe OpenAPI und unterstützen Mocking, Tests und nachgelagerte Dokumentationen. Sie unterscheiden sich in der Art und Weise, wie Sie die Spezifikation erstellen und versionieren.
| Design-First-Modus | Spec-First-Modus (Beta) | |
|---|---|---|
| Editor | Visuelle Formulare und Schema-Baum | IDE-ähnlicher YAML/JSON-Code-Editor |
| Spezifikationsformat | OpenAPI (für Sie generiert) | OpenAPI / Swagger, manuell geschrieben |
| Git-Workflow | Branch-Unterstützung innerhalb von Apidog | Bidirektionale Synchronisierung mit GitHub, GitLab, Azure DevOps (Git-Verbindung); Commit und Push direkt aus der App |
| Validierung | Durch Formulareingaben erzwungen | Inline-Syntaxprüfung und Auto-Vervollständigung |
| Navigation | Endpunktliste und Ordner | Automatisch geparste Gliederung in der linken Seitenleiste |
| Lernkurve | Niedrig; keine OpenAPI-Kenntnisse erforderlich | Höher; setzt OpenAPI-Kenntnisse voraus |
| Am besten für | Teams mit gemischten Fähigkeiten, schnelles Onboarding | Ingenieure, die die Spezifikation als Code behandeln |
Welches Team sollte welchen Modus wählen
Verwenden Sie den Design-First-Modus, wenn nicht alle Ihre Mitwirkenden OpenAPI-Experten sind. Produktmanager, QS und Junior-Ingenieure können alle Endpunkte hinzufügen oder überprüfen, ohne die Spezifikationssyntax lernen zu müssen. Es ist auch der schnellere Weg, wenn Sie eine neue API von Grund auf neu starten und schnell durch die Struktur kommen möchten, ohne sich um die Formatierung kümmern zu müssen.
Verwenden Sie den Spec-First-Modus, wenn Ihre Spezifikation bereits in einem Git-Repository neben Ihrem Dienstcode liegt oder liegen sollte. Backend-Teams, die API-Änderungen in Pull Requests überprüfen, Spec-Linting in CI ausführen oder eine einzige kanonische YAML-Datei über Tools hinweg verwenden möchten, werden sich wohlfühlen. Die bidirektionale Synchronisierung bedeutet, dass Apidog aufhört, eine separate Kopie der Wahrheit zu sein, und zu einem Fenster wird, das die gleiche Datei anzeigt, die Ihr Repository enthält.
Ein praktischer Mittelweg: Viele Teams entwerfen neue Endpunkte im Design-First-Modus aus Geschwindigkeitsgründen und wechseln dann zum Spec-First-Modus, sobald die API ausgereift ist und die Git-Überprüfung Priorität hat. Die Modi sind keine Konkurrenzprodukte. Sie sind zwei Ansichten eines Vertrags.
So wechseln Sie die Modi
Der Wechsel ist ein einziger Umschalter. Öffnen Sie das API-Modul in Ihrem Apidog-Projekt und schauen Sie in die untere linke Ecke, wo sich der Modus-Umschalter befindet. Schalten Sie ihn um, und derselbe Vertrag wird im anderen Modus gerendert.
Einige Dinge, die Sie beim Wechsel beachten sollten:
- Die zugrunde liegende Spezifikation wird geteilt, sodass Ihre Endpunkte, Schemas und Beispiele übertragen werden. Sie ändern die Bearbeitungsoberfläche, nicht die API neu.
- Um die Git-Synchronisierung des Spec-First-Modus zu nutzen, verbinden Sie zuerst Ihr GitHub-, GitLab- oder Azure DevOps-Repository. Sobald verbunden, zeigt der Synchronisierungsindikator an, ob Ihre Änderungen committet und gepusht wurden.
- Da sich der Spec-First-Modus in der Beta-Phase befindet, testen Sie ihn in einem Projekt, in dem Sie das Synchronisierungsverhalten bestätigen können, bevor Sie sich für einen Produktionsvertrag darauf verlassen.
Sie können je nach Bedarf hin- und herwechseln, behandeln Sie die Wahl also eher als Standardeinstellung denn als Verpflichtung.
FAQ
Ist Spec-First dasselbe wie Contract-First?
In der Praxis ja. „Spec-First“ und „Contract-First“ bedeuten beide, dass Sie die API-Spezifikation vor der Implementierung erstellen, und beide behandeln diese Spezifikation als die Quelle der Wahrheit. 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 die bidirektionale Git-Synchronisierung direkt mit GitHub und GitLab. Azure DevOps funktioniert über eine generische Git-Verbindung, sodass Sie Ihre Spezifikationsdatei auch mit einem Azure-gehosteten Repository synchronisieren können.
Kann ich ohne Datenverlust vom Design-First- zum Spec-First-Modus wechseln?
Ja. Beide Modi lesen und schreiben denselben zugrunde liegenden Vertrag, sodass Ihre Endpunkte, Schemas und Beispiele intakt bleiben, wenn Sie den Umschalter unten links im API-Modul betätigen. Sie tauschen den Editor aus, nicht die Daten.
Sie sind sich nicht sicher, welcher Modus zu Ihrem Team passt? Öffnen Sie das API-Modul, probieren Sie den Modus-Umschalter unten links aus und entwerfen Sie Ihren nächsten Endpunkt auf beide Arten. Der Vertrag ist in beiden Fällen derselbe; wählen Sie die Oberfläche, die der Arbeitsweise Ihres Teams entspricht.