OpenAPI direkt in VS Code schreiben – geht das?

OpenAPI-Spezifikationen (OAS) beschreiben standardisiert und Programmiersprachen-unabhängig HTTP-APIs. Für die Erstellung von OAS gibt es verschiedene Möglichkeiten, häufig werden sie auch generiert. Das ist aber nicht für alle Programmiersprachen und Systeme möglich. Darum gibt es Editoren wie den Swagger-Editor und Stoplight Studio, die das Schreiben und Bearbeiten von OAS unterstützen. Aber geht das auch in der alltäglich verwendeten IDE?

Dieser Artikel evaluiert VS Code als alternativen Editor für OAS, vergleicht verschiedene Erweiterungen zu diesem Zweck und stellt exotische Ideen, interessante Features, Lücken und Bugs aus der breiten Palette der VS-Code-Erweiterungen vor.

Insgesamt wurden 15 VS-Code-Erweiterungen für OpenAPI untersucht. Dabei wurden sieben Erweiterungen nach einem kurzen Test aufgrund von größeren Bugs und Fehlern verworfen und die verbliebenen Erweiterungen hinsichtlich folgender Merkmale verglichen:

1. Umfang: Welche OpenAPI-Versionen werden unterstützt? Welche Dateitypen (YAML/JSON) werden unterstützt?
2. Lint: Warnungen und Fehler in Syntax und Struktur der OAS werden erkannt, markiert und erklärt.
3. Auto-Vervollständigung: Ein Autovervollständigungs-Feature gibt Vorschläge zur Vervollständigung der Zeile, wenn der Entwickler zu tippen beginnt und es gibt Vorschläge zu möglichen Schlüsselwörtern und Werten, bevor der Entwickler zu tippen beginnt.
4. Preview: Eine Vorschau der resultierenden Dokumentation der API kann generiert werden.
5. Template: Es wird eine einfache OAS als Beispiel für OpenAPI-Newbies oder als Quickstart-Template bereitgestellt.
6. Template-Snippets: Die Erweiterung erstellt YAML/JSON-Snippets für die einzelnen Abschnitte und Elemente der OAS. Die Entwickler müssen sich so nicht genau an die Struktur der OAS erinnern, sondern können einfach das vorgefertigte Snippet-Template ausfüllen.
7. Inline-Dokumentation und Erklärungen: Es werden Erklärungen zur Bedeutung der verschiedenen Abschnitte und Schlüsselwörter der OAS bereitgestellt.
8. Visualisierung: Die OAS kann visualisiert werden, zum Beispiel als Übersichtsgrafik.

Dazu wurden folgende OAS  zum Testen verwendet:

• OpenAPI v2.0/Petstore: Ein einfaches Beispiel mit rund 150 Zeilen
• OpenAPI v3.0/Petstore: Ein einfaches Beispiel mit rund 150 Zeilen
• OpenAPI v3.0/Swagger-Petstore: Ein ausführlicheres Beispiel mit rund 800 Zeilen und  mehreren verschiedenen Operationen

Vergleich der OpenAPI-VS-Code-Erweiterungen

Die Übersicht der Funktionalitäten der verschiedenen Erweiterungen sind in der Tabelle unten zusammengefasst. Dabei sind die VS-Code-Erweiterungen sortiert nach Popularität (gemessen an der Anzahl der Downloads).

Es gibt nur zwei Erweiterungen, die viele Funktionen integriert haben. Das sind die Erweiterungen OpenAPI (Swagger) Editor und Redocly OpenAPI. Die anderen Erweiterungen haben sich auf eine Funktion spezialisiert, wie Preview oder Linting. Meistens werden die OpenAPI-Versionen v2.0 und v3.0 sowie beide Dateitypen (JSON und YAML) unterstützt. 

Highlights

Eine Liste an Funktionalitäten allein kann das Verhalten einer Erweiterung nicht vollständig beschreiben. Daher stellt dieser Artikel im Folgenden interessante und inspirierende Features vor, die bei der Recherche aufgefallen sind. 

OpenAPI v3.0/Swagger-Petstore: Die Erweiterung für alles mit interaktiver Übersicht

Die Erweiterung OpenAPI (Swagger) Editor enthält alle Basics (Linting, Intellisense, Dokumentation-Preview) zu einem gewissen funktionellen Grad und unterstützt auch Snippet-Generierung. Ein Highlight ist die einfache, navigierbare Übersicht über die OAS in der Seitenleiste. Über diese bekommt man nicht nur eine Zusammenfassung der OAS, sondern kann auch im Code zu der gewünschten Stelle springen.

Seitenleiste zur Übersicht und Navigation

So sieht die Übersicht über die ausführliche OpenAPI v3.0/Swagger-Petstore OAS aus. Die einzelnen Elemente kann man aufklappen und den Inhalt einsehen.

Bei einem Mausklick auf ein Element der Übersicht springt man automatisch zu dem dazugehörigen Code-Abschnitt. Die Seitenleiste dient also zusätzlich zur Navigation.

Redocly OpenAPI: Cursor-Kontext und Formulare

Die Erweiterung Redocly OpenAPI ist vielseitig und stellt Validierung, Auto-Completion und eine Preview-Dokumentation bereit (die man allerdings ohne Redocly-Account nicht öffnen kann). Besonders interessant sind jedoch die interaktiven Formulare und Kontext-bewussten Hilfetexte, die die VS-Code-Erweiterung im sogenannten Cursor-Kontext bereitstellt.

Der Cursor-Context öffnet sich per default in der Übersicht, dem „Root“-Verzeichnis der OAS. Zu jedem Abschnitt, jedem Unterabschnitt und vielen weiteren Schlüsselwörtern werden im Cursor-Kontext Erklärungstexte bereitgestellt.

Folgt man dem Navigationslink zum Beispiel zum Info-Abschnitt, springt man im Code zu der richtigen Stelle und kann auch im Cursor-Kontext den Abschnitt mittels interaktiver Formulare bearbeiten. 

Leider sind für viele der im „Root“ verlinkten Abschnitte keine Formulare vorhanden. Zum Beispiel beim Server-Abschnitt wird man darauf vertröstet, dass der Abschnitt bald implementiert werden wird.

Allerdings sind bei einer anderen Cursor-Position Formulare vorhanden: 

Dieses Phänomen der schlecht verlinkten Formulare ist mehrfach zu finden (zum Beispiel auch für die Tags), allerdings gibt es auch leider Abschnitte, für die tatsächlich keine Formulare zu existieren scheinen. Manchmal bilden die Formulare auch einfach nicht den notwendigen Funktionsumfang des OAS-Abschnitts ab. Nichtsdestotrotz bietet die Redocly-Erweiterung für OpenAPI-Anfänger eine starke Unterstützung.

Preview für Swagger UI und ReDoc

Alle Erweiterungen, die überprüft wurden, haben für den Preview der Dokumentation entweder die Swagger UI (die UI des populären Swagger Editors) oder die ReDoc (von Redocly) in VS Code integriert. Dabei ist auch die Funktion enthalten, mit der Beispiel-Requests für einen Endpunkt automatisch generiert werden.

• Beide Preview-Typen sind im OpenAPI (Swagger) Editor integriert. 
• Wer nur den Swagger UI Preview nutzen möchte, kann auch die Erweiterung V-Swagger nutzen. Dieser enthält keine anderen Funktionalitäten (Linting, etc.) sondern wirklich nur den Preview.
• Wer nur den ReDoc Preview haben möchte, kann auch die Erweiterung ReDoc Viewer nutzen.

Openapi-lint: OAS konvertieren und bündeln

Die Erweiterung openapi-lint kann zwischen den OpenAPI Versionen 2.0 und 3.0 und zwischen den YAML- und JSON-Dateiformaten konvertieren. Außerdem kann sie das „Bundling“ übernehmen. Bundling führt mehrere OpenAPI-Dateien zu einer Datei zusammen, wobei externe Referenzen zu lokalen Referenzen aufgelöst werden. Alle entstehenden Dateien werden in einem neuen Fenster geöffnet, sodass die alte Datei nicht überschrieben wird.

OAS2Tree: Eine Baum-Visualisierung der Pfadstruktur

Interessant, aber leider hat OAS2Tree in VSCode nicht funktioniert.

OAS2Tree transformiert eine OAS zu einer Baum-Visualisierung. Die Knoten des Baums sind interaktiv, geben Detailinformationen und lassen sich aufklappen und zusammenfassen. Allerdings sind sie nicht mit dem entsprechenden Code-Abschnitt im OpenAPI-File verlinkt.

Leider hat die VS-Code-Erweiterung von OAS2Tree nicht funktioniert. Beim Öffnen der Live-Visualisierung kam unabhängig von der gewählten OAS stets dieselbe Fehlermeldung: Topology is closed.

Die Web-Version von OAS2Tree funktioniert jedoch wunderbar. Die Baum-Visualisierung bildet dabei den Paths-Abschnitt der OAS ab. Dieser definiert die Endpunkte der API und die darauf verfügbaren HTTP-Methoden.

Die Baum-Visualisierung des Beispiels OpenAPI v3.0/Petstore in der Web-Version von OAS2Tree.

Der Root-Knoten / wird durch den Endpunkt /pets erweitert. /pets wird durch den Unterpfad /pets/{id} erweitert. Jeder Endpunkt wird durch die auf ihm verfügbaren HTTP Methoden erweitert. GET wird dabei als grüner Knoten dargestellt, POST als gelber Knoten und DELETE als roter Knoten.

Wenn man mit der Maus über einen Knoten hovert, lässt sich der vollständige Pfad ablesen.

Auf die HTTP-Methoden folgen zwei Typen von Blattknoten. Sie lassen sich mit einem Mausklick aufklappen.

• (?): Die Parameter der Methode. In dem obigen Beispiel gibt es den Parameter tags vom Datentyp array und den Parameter limit vom Typ integer.
• (>) Die responses (HTTP-Antworten) der Methode. Im Beispiel gibt es die HTTP-Antwort 200 OK und die default Antwort-Spezifikation, welche das Verhalten für alle möglichen HTTP-Antworten außer 200 OK zusammenfasst.

Der Baum für die ausführliche Swagger-Petstore OpenAPI v3.0 Spezifikation. Bei zunehmender Größe der OAS wird der Baum allerdings schnell groß und etwas unübersichtlich.

Fazit

Ja, man kann definitiv OAS-Dateien in VS Code schreiben! Die Erweiterungen enthalten einen bunten Blumenstrauß an Funktionalitäten und die meisten sind auch sehr zuverlässig in dem, was sie tun. In einigen Erweiterungen ließen sich aber auch einige Bugs und Lücken finden. Es wäre großartig, wenn diese bald gefixt werden, sodass auch diese guten Ideen so viel genutzt werden, wie sie es verdienen. 

Alles in allem können aufgrund der vorangegangenen Recherche folgende Setups für OpenAPI in VSCode empfohlen werden:

Empfehlenswert ist, die Erweiterung OpenAPI (Swagger) Editor in Kombination mit einer Linting-Erweiterung wie zum Beispiel Spectral zu nutzen. Der OpenAPI (Swagger) Editor kann nämlich zwar fast alles gut, aber sein Linting ist nicht ausreichend. Mit diesem Setup werden die OpenAPI-Versionen v2.0-v3.0 und beide Dateitypen unterstützt.

Alternativ kann man Redocly OpenAPI nutzen. Dieses bietet mehr Unterstützung für Anfänger mit OpenAPI. Allerdings ist die Erweiterung gerade in den interaktiven Formularen, die für Anfänger besonders attraktiv sein können, lückenhaft und etwas verbuggt. Zudem muss man Redocly OpenAPI mit einer Preview-Erweiterung nutzen, wenn man keinen Redocly Account anlegen möchte. Mit diesem Setup werden die OpenAPI-Versionen v2.0-v3.1 unterstützt. Als Dateityp kann nur YAML verwendet werden.