Im Dunstkreis der OpenAPI-Spezifikation OAS-Alternativen – spannende und freie OpenAPI-Tools

Anbieter zum Thema

netfiles GmbH

OpenAPI ist zweifelsohne die wichtigste API-Spezifikation unserer Zeit – aber erst durch Tooling wird sie selbst zum hilfreichen Tool. Die spannendsten Tools im Überblick.

Die OpenAPI-Spezifikation ist zweifelsohne der Marktführer. Und das nicht, weil sie selbst unbedingt besser wäre als die wenigen Alternativen. Vielmehr, weil OAS eine riesige, aktive Community vorweisen kann – und somit auch ein großes Angebot an Open-Source-Software von Dritten.

OAS-Alternativen

RAML, API Blueprint & Co. – OpenAPI-Konkurrenz?

Das wesentliche Tooling liefert bereits Smartbear selbst: Neben den kommerziellen Angeboten über SwaggerHub gibt es mit Swagger Codegen, Editor und UI die Werkzeuge, um eine OAS-API zu schreiben und daraus Server- und Client-Stubs sowie eine interaktive Dokumentation abzuleiten. Alle drei Tools bekommen sind als Editor auch direkt im Browser erhältlich – auch in einer Next-Gen-Variante.

OpenAPI Tools

Eine Alternative zu diesem Swagger-Trio bietet der OpenAPI Generator, der ebenfalls als Online-Service zur Verfügung steht. Der große Unterschied: Die originären Tools stammen von Smartbear. Diese stammt hingegen von der Community, hier in Form der OpenAPI Tools. Zudem fehlt der eigentliche Editor, der Online-Dienst setzt auf bereits bestehende JSON-Dateien, wahlweise lokal oder per URL anzugeben.

Spannend sind hier die unterstützten Formate. Gibt es bei Swagger derzeit rund 16 Sprachen, sind es bei OpenAPI Tools Dutzende. Darunter zum Beispiel Bash, Haskell, Kotlin, Perl, PowerShell, Ruby, Typescript und Zapier auf der Client-Seite. Server-Stubs lassen sich unter anderem in C#, C++, Julia, Rust oder natürlich Python erzeugen. Besonders spannend für die Dokumentation: Neben HTML, Markdown und Asciidoc wird auch das allgegenwärtige Confluence Wiki von Atlassian unterstützt.

Hinzu kommt noch ein gutes Dutzend weiterer Tools, darunter zum Beispiel OpenAPI-Diff zum Vergleichen zweier OAS-Dokumente, ein Style-Validator, diverse Installer, Beispielcode und weiterer Kleinkram. Die zugehörige Community auf GitHub ist groß und aktiv, allerdings wird der Großteil der Arbeit von einem Entwickler geleistet. Auch namhafte Sponsoren wie Datadog oder dm Tech sind mit dabei.

Ein kleiner Haken bei der ganzen Geschichte: Die Online-Version scheint nicht funktionsfähig, korrekte JSON-Dateien werden akzeptiert und ignoriert – ein entsprechendes Issue liegt im Projekt schon lange brach. Generell ist die Liste an Issues umfangreich.

OpenAPI (Swagger) Editor

Unter dem etwas sperrigen Namen OpenAPI (Swagger) Editor bietet API-Plattform-Betreiber 42Crunch eine sehr gut funktionierende Hilfe für OpenAPI-Dateien in Visual Studio Code an. Die Erweiterung besteht aus drei Teilen: Zunächst gibt es eine Vorschau auf die originale, interaktive Swagger-UI-Dokumentation. Im Editor gibt es zudem eine vernünftige Auto-Vervollständigung für mögliche OpenAPI-Elemente und deren Werte. Und drittens nistet sich eine Explorer-Spalte ein, über die sich auch in größeren Spezifikationen navigieren lässt.

Es gibt weitere OpenAPI-Plugins für VSC, allerdings auch viele, die nicht (mehr) einwandfrei funktionieren. Insbesondere Vorschau-Plugins gibt es reichlich, eine schlanke, gut funktionierende Alternative wäre hier zum Beispiel vs-openapi-designer, das trotz des Namens schlicht die Swagger-UI-Vorschau einrichtet.

Optional können über eine Registrierung auch Funktionen der 42Crunch-Plattform direkt in VSC genutzt werden.

OpenAPI 3 Definitions Designer

Ein nettes kleines Tool ist der Online-Dienst OpenAPI 3 Definitions Designer, mit dem Sie genau das tun können, was der Name schon sagt – OAS-Dokumente in Version 3 erstellen.

Der Editor vereinfacht im Grunde die Komplexität der Syntax. Über simple Eingabemasken lassen sich hier Schemas und Pfade definieren, die entsprechend in YAML- und JSON-Quelltext umgesetzt werden.

Um „mal eben“ eine Idee in eine API-Definition zu gießen, aus der dann binnen weniger Minuten eine Demo gebaut werden kann, ist die Seite wirklich praktisch.

OpenAPI DevTools

Weiter geht es mit den generischen, kaum auseinander zu haltenden Toolnamen: OpenAPI DevTools ist eine Erweiterung für Chrome, funktioniert hier in Tests nicht wirklich immer oder zuverlässig, verfolgt aber ein hitverdächtiges Konzept: Das Tool erstellt automatisch OpenAPI-Definitionen allein durch die Nutzung von Webseiten! Theoretisch könnten Sie also Ihre eigene Homepage nutzen und sich anschließend ein fertiges OAS-Dokument im JSON-Format herunterladen.

Die generierte Swagger-UI landet auch direkt im Fenster der Entwickler-Tools in Chrome. Da der Einsatz nicht ganz intuitiv ist: Zum Ausprobieren müssen Sie die Dev-Tools aufrufen (F12), dann den – in der Regel hinter dem „Menü“ versteckten – Eintrag „OpenAPI“ öffnen und den Rekorder aktivieren. Dann beginnt die App sofort, Daten und Endpunkte zu sammeln.

Direkt brauchbare Ergebnisse ließen sich hier in Tests nicht bekommen, meist kamen irgendwelche Fehlermeldungen dazwischen. Allerdings sind die erzeugten Dokumente durchaus nützlich zum Verstehen der Services und zum tatsächlichen Bauen von OAS-Schnittstellen.

OAS RAML Converter

Beim OAS-RAML-Konverter ist der Name nun wieder Programm, welches dann von überschaubarem Nutzen ist: OAS-2.0 oder -3.0-Dokumente werden ins RAML-Format konvertiert und umgekehrt.

Nützlich ist das in zweierlei Hinsicht: Zum einen möchte RAML-Anbieter Mulesoft die eigentliche Entwicklung einer API immer noch in RAML sehen – wegen eines einfacheren Formats. Nach der Entwicklung ist aber klar, dass weitere Tests und die produktive Umsetzung in OAS geschehen werden, daher der Konverter.

Durch die Side-by-Side-Ansicht hilft die Webseite aber auch, den Unterschied zwischen beiden Formaten und den Aufbau einer API-Definition an sich zu verstehen. Probieren Sie es einfach mal mit einer der vielen Demo-YAMLs aus!

OpenAPI Changes

„The world's sexiest OpenAPI diff tool.“ ist eine selbstbewusste Selbstbeschreibung – und OpenAPI dürfte darin auch noch weggelassen werden! OpenAPI Changes macht etwas in der Welt von Open Source, Entwicklung und Terminals wirklich Seltenes: Spaß durch Eye-Candy.

Bei dem Diff-Betrachter ist Eye-Candy allerdings kein reiner Selbstzweck. OAS-Dokumente werden schnell sehr umfangreich und dürften sich in der Entwicklung sehr dynamisch verhalten – sprich, es wird ständig an jeder Ecke herum gefeilt. Und durch die Aufbereitung, sei es im Terminal oder im Browser, inklusive Baum – und grafischer Ansichten, Timeline, Berichten und so weiter, werden Differenzen und Änderungen wunderbar sichtbar.

Tool-Verzeichnisse

Natürlich handelt es sich hier um einen winzigen Auszug des OpenAPI-Universums. Allerdings sind sehr viele Tools auch nur über proprietäre Plattformen zu bekommen und auch nicht wirklich OAS-spezifisch, sondern allgemein auf API-Entwicklung und -Dokumentation gemünzt.

Und es gibt Addons für Linter, Vorschau und Auto-Vervollständigung auch für andere IDEs als VSC.

Zum Schluss daher hier noch zwei Verzeichnisse, die möglichst umfangreich sein wollen (dafür allerdings auch reichlich nicht mehr aktive Projekte listen):

Unter openapi.tools gibt es eine ausgiebige, per GitHub-Repository gepflegte Liste, für die auch eigene Vorschläge eingereicht werden können.

Die OpenAPI Initiative selbst listet derzeit ganze 1.552 Tools (inklusive Doppelungen) in mehreren Dutzend Kategorien.

(ID:50189032)