In jedem API-Team, mit dem ich gearbeitet habe, gibt es zwei Lager.
Die einen schreiben ihre OpenAPI-Spezifikation von Hand, committen sie in ein specs/-Verzeichnis und betrachten Git als die Quelle der Wahrheit. Die anderen klicken sich durch einen visuellen Designer, exportieren die Spezifikation, wenn CI sich beschwert, und patchen die Abweichungen, die sich seit letztem Dienstag zwischen den beiden Darstellungen angesammelt haben.
Ich habe in beiden Lagern gelebt. Das erste ist am ersten Tag langsamer und am neunzigsten schneller. Das zweite ist das Gegenteil. Und bis vor etwa einem Monat bediente das API-Design-Tool, das ich am häufigsten verwende – Apidog – nur wirklich das zweite Lager. Sein visueller Designer ist ausgezeichnet. Sein YAML-Roundtrip war eine Funktion, die man in der Code-Überprüfung verteidigen musste.
Mitte April erschien dann der Spec-First Modus (Beta) im Dialog für neue Projekte. Ich habe bewusst nicht am Starttag darüber geschrieben. Ich wollte ihn zuerst an etwas Realem ausprobieren und lange genug warten, damit frühe Bugs eine Chance hatten, aufzutauchen. Ein Monat ist ungefähr die richtige Zeitspanne. Dieser Beitrag fasst zusammen, was ich nach einem Vormittag mit der Beta an einer OpenAPI-Spezifikation aus einem meiner Nebenprojekte herausgefunden habe – was ich einem Teamkollegen erzählen würde, bevor er es ausprobiert, und wo es passt und wo nicht.
Was der Spec-First Modus wirklich ändert
Kurz gesagt: Apidog bietet jetzt zwei Projektmodi, die darunter liegend wirklich unterschiedliche Produkte sind.
Der Standardmodus ist das, was die meisten Leute kennen. Sie klicken auf „+ Neues Projekt“, erhalten einen Ordnerbaum und visuelle Formulare und erstellen Endpunkte, indem Sie Felder ausfüllen. Die OpenAPI-Spezifikation wird im Hintergrund generiert. Das funktioniert, besonders für Teams, die noch keine starke YAML-Gewohnheit haben.
Der Spec-First Modus ersetzt den Formular-Editor durch einen echten Code-Editor für reine .yaml- und .json-Dateien, plus eine bidirektionale Synchronisation mit Ihrem Git-Repository. Ihre OpenAPI-Spezifikation ist die Datei auf der Festplatte, nicht eine Serialisierung von Klicks. Es gibt Syntaxhervorhebung, Autovervollständigung gemäß dem OpenAPI-Schema und einen „Echtzeit-Verzeichnis-Parsing“-Bereich, der eine Endpunkt-Gliederung in der Seitenleiste aus Ihrem Code erstellt, während Sie tippen.
Dieses letzte Detail wäre das, womit ich beginnen würde, wenn ich dies einem Skeptiker vorführen würde. Der Grund, warum visuelle Designer existieren, ist nicht, dass YAML schwer ist – es ist, weil YAML die Struktur verbirgt, bis man schon daran vorbeigescrollt ist. Die Gliederungsansicht von Apidog löst das, ohne dass man die Datei aufgeben muss. Man schreibt die Spezifikation, man bekommt Navigation. Die beiden existieren auf dem Bildschirm nebeneinander.
Die These, falls es eine gibt: Spec-First-Entwicklung ging nie darum, Texteditoren zu bevorzugen. Es ging darum, wem das Artefakt gehört. Der Spec-First Modus macht das Artefakt zur Datei in Ihrem Repository, Punkt. Die Benutzeroberfläche ist ein Fenster dazu, kein Wrapper darum.
Die Einrichtung, Ende zu Ende
Hier ist der Weg, den ich gegangen bin. Es dauerte weniger als zehn Minuten, wovon der größte Teil die Git-Autorisierung in Anspruch nahm.
1. Erstellen Sie das Projekt im richtigen Modus. Vom Projektbildschirm aus: + Neues Projekt → Allgemein → Spec-First Modus. Die Modusauswahl ist leicht zu übersehen, wenn Sie seit einem Jahr Projekte im Autopilot erstellen – der Allgemeine Modus ist als „Empfohlen“ gekennzeichnet und Ihr Blick gleitet einfach am zweiten Kachel vorbei. Nehmen Sie sich hier Zeit.
2. Verbinden Sie sich mit Ihrem Git-Repository. Scrollen Sie zu Mit Git-Repository verbinden und autorisieren Sie Ihren Anbieter. Ich habe GitHub verwendet; die Dokumentation behandelt die anderen. Wählen Sie dann die Organisation, das Repository und den Main Branch aus. Apidog synchronisiert die Spezifikationsdateien in diesem Branch als Ihre Arbeitskopie.
3. Konfigurieren Sie das Projekt. Geben Sie einen Projektnamen ein, legen Sie Team-Berechtigungen fest und klicken Sie auf Erstellen. Die erste Synchronisation zieht alle .yaml- und .json-Dateien, die sich im Repository befinden, in den Arbeitsbereich von Apidog.
4. Bearbeiten Sie die Spezifikation wie eine Datei, nicht wie ein Formular. Öffnen Sie eine der YAML-Dateien. Sie erhalten einen echten Editor, schema-bewusste Autovervollständigung und die Endpunkt-Gliederung, die sich in der Seitenleiste während des Tippens materialisiert. Wenn Sie schon einmal Zeit in VS Code mit der OpenAPI-Erweiterung verbracht haben, wird sich dies vertraut anfühlen – außer dass die Gliederung mit der Navigation verbunden ist und das Klicken auf einen Endpunkt zur richtigen Zeile springt.
5. Committen und Pushen. Oben rechts, Commit & Push. Der Dialog öffnet sich zu einem Abschnitt Änderungen, der modifizierte Dateien auflistet, einem Feld Commit-Nachricht und zwei Schaltflächen: Pushen oder Alle Änderungen verwerfen. Es gibt keinen separaten Staging-Schritt – alles unter Änderungen geht in den Commit. Das ist eine bewusste Vereinfachung, und für die meisten Spec-Bearbeitungs-Workflows ist es die richtige Entscheidung.
6. Beobachten Sie die Synchronisierungsanzeige. Unten links – Sie können sie in Abbildung 1 als Gerade synchronisiert sehen. Sie zeigt Ihnen an, ob Ihre lokalen Änderungen gepusht, gepullt oder nicht mit dem Remote synchronisiert sind. Ich ließ dies in einer Ecke meines Bildschirms geöffnet, und es wurde das, dem ich mehr vertraute als den modalen Dialogen. Wenn die Anzeige grün ist, stimmen Sie und das Repository überein.
Das ist der gesamte Funktionsumfang. Sechs Schritte, keine separate Synchronisations-Engine zum Konfigurieren, keine Plugins zum Installieren.
Was mir auffiel, was die Dokumentation nicht verrät
Drei Dinge, die es wert sind, erwähnt zu werden, alle aus einem Vormittag des Ausprobierens.
Die Gliederungsansicht aktualisiert sich schneller, als ich erwartet hatte. Ich habe in der Vergangenheit mehrere „Live-OpenAPI-Editoren“ verwendet, und die meisten davon parsen beim Speichern neu, was eine 30-sekündige Verzögerung zwischen dem Hinzufügen eines Endpunkts und dessen Anzeige in der Seitenleiste bedeutet. Die Gliederung von Apidog aktualisierte sich, während ich tippte – nah genug an sofort, dass ich aufhörte zu überprüfen. Das klingt nach einer Kleinigkeit. Ist es aber nicht. Es ist der Unterschied zwischen dem Vertrauen in die Gliederung als Navigationshilfe und dem Überprüfen als Statusbericht.
Die Git-Integration ist wirklich bidirektional. Ich habe dieselbe Datei in meiner lokalen Kopie bearbeitet und vom Terminal aus gepusht, während Apidog geöffnet war. Apidog bemerkte dies, die Synchronisationsanzeige wechselte auf „im Rückstand“, und ein Klick zog die Änderungen ohne Merge-Dialog in den Editor. Die bidirektionale Synchronisation, die die Dokumentation verspricht, ist die tatsächliche Erfahrung, keine Marketingzusammenfassung. Wenn Sie einen Teamkollegen haben, der sich weigert, etwas anderes als Vim zu verwenden, kann er Vim weiterverwenden, und Sie können Apidog weiterverwenden, und die Datei im Repository bleibt das einzige, was Sie beide bearbeiten.
Es gibt keinen Notausgang zurück zum visuellen Designer im selben Projekt. Dies ist beabsichtigt, aber es ist gut zu wissen, bevor man sich festlegt. Wenn Sie den Spec-First Modus bei der Erstellung wählen, ist dieses Projekt spec-first. Sie können ein Projekt nicht mitten im Prozess wechseln, da die zugrunde liegenden Datenmodelle unterschiedlich sind. Für ein Team, das beide Modi für dieselbe Spezifikation nutzen möchte, sieht der Workflow wie folgt aus: Bewahren Sie die Spezifikation in einem Repository auf, weisen Sie ein Spec-First-Projekt darauf hin und lassen Sie die Benutzer des visuellen Modus ein separates Projekt öffnen, das aus derselben Quelle importiert. Nicht nahtlos, aber praktikabel.
Wo es passt und wo nicht
Ich werde dies in der Produktion einsetzen. Das ist die direkteste Antwort, die ich geben kann. Die Kombination aus einem echten Editor, einer Autovervollständigung, die das OpenAPI-Schema respektiert, und einer Synchronisationsanzeige, der ich vertrauen kann, ist das, was ich mir seit zwei Jahren von Apidog gewünscht habe.
Aber hier ist die ehrliche Version, für wen das ist.
Es passt, wenn Sie OpenAPI bereits von Hand schreiben oder schreiben möchten. Es passt, wenn Ihr CI spectral lint ausführt oder Client-SDKs aus der Spezifikation generiert und die Spezifikation sowieso in Git leben muss. Es passt, wenn Sie einen Ingenieur im Team haben, der sonst Pull-Requests gegen die YAML-Datei aus VS Code öffnen würde, und Sie möchten, dass sich alle auf ein Tool einigen, ohne sie von ihrer Tastatur zu zwingen. Und es passt besonders gut, wenn Sie die Abweichung zwischen „der Spezifikation in Apidog“ und „der Spezifikation im Repository“ mit einem make export-Schritt verwaltet haben, dem niemand vertraut.
Es passt nicht, wenn Ihr Team noch nie mit OpenAPI gearbeitet hat und der visuelle Designer der Grund ist, warum es überhaupt beitragen kann. Für diese Teams ist der Standardmodus immer noch die richtige Wahl. Der Spec-First Modus tauscht einfache Einarbeitung gegen Genauigkeit, und dieser Tausch ist falsch, wenn die meisten Ihrer Beitragenden keine API-Spezialisten sind.
Es passt auch noch nicht für Teams, die beide Modi im selben Projekt mischen müssen. Die Beta ist in dieser Hinsicht wirklich eine Beta. Ich würde erwarten, dass sich dies in den nächsten Releases entschärft.
Das Fazit
Spec-First-Entwicklung bedeutete früher, auf API-Design-Tools zu verzichten. Man lebte entweder in YAML und gab die Test-Runner und Mock-Server auf, oder man lebte in einem visuellen Designer und gab Git als Quelle der Wahrheit auf. Der interessante Schritt im Spec-First Modus ist, dass Apidog aufgehört hat, Sie zur Wahl zu stellen.
Die Datei in Ihrem Repository ist die Datei im Editor. Die Gliederung ist eine Ansicht, kein Zustand. Die Git-Synchronisation ist die Verbindung, kein Feature. Wenn Sie auf eine API-Plattform gewartet haben, die Spec-First ernst nimmt, anstatt es als Exportoption zu behandeln, dann ist dies diejenige, die ich ausprobieren würde.
Die Beta ist heute im Dialog für neue Projekte live. Laden Sie Apidog herunter, wählen Sie den Spec-First Modus bei der Erstellung und verweisen Sie auf ein Repository, dem Sie bereits vertrauen. Der erste Commit dauert zehn Minuten. Die Entscheidung, ob man es beibehält, dauert etwa eine Woche.