Swagger: Mehr Komfort bei der API-Entwicklung

Eine Dokumentation ist in Entwicklungsprojekten sehr zeitaufwendig und Außenstehende erkennen oft nicht, wie hilfreich sie für die Wartung und Weiterentwicklung von Systemen ist. Das macht sich spätestens dann bemerkbar, wenn Wartung und Erweiterung nicht von dem Team durchgeführt werden, die das System entwickelt haben – was eher die Regel als die Ausnahme ist.

Noch wichtiger ist die Dokumentation der APIs, also der Application Programming Interfaces oder zu Deutsch: Schnittstellen. Sie verbinden Anwendungen miteinander und die Applikationen mit Datenquellen und anderen Systemen. Es gibt heute kaum noch Anwendungsfälle, in denen nicht eine Vielzahl von APIs die zentrale Rolle in Software-Verbindungen spielen. Um aber die Schnittstellen verwenden zu können, muss man auch ihre Struktur und Funktionen kennen. Das ermöglicht die OpenAPI-Spezifikation Swagger, die als offenes Beschreibungsformat dabei hilft, den Überblick über die unterschiedlichen Fähigkeiten von APIs zu bewahren. Mit Swagger können auch Personen, die nicht direkt im Entwicklungsprozess involviert waren, APIs bereitstellen: Sie sehen die genutzten Schnittstellen und können sie gleich dokumentieren.

Die Beschreibung von APIs war in der Vergangenheit aufgrund von unterschiedlichen Technologien und Programmiersprachen sehr komplex. Ein erster wichtiger Ordnungspunkt: Für die Entwicklung von APIs ist mittlerweile REST das Programmierparadigma. Webseiten wie Google, Amazon und Twitter verwenden RESTful APIs. Früher wurden Schnittstellen in der Web Services Description Language WSDL beschrieben. Rein technisch lassen sich mit WSDL 2.0 auch REST-APIs beschreiben, was aber unter Entwicklern als sehr umständlich gilt. Die Web Application Description Language (WADL) sollte dieses Problem lösen, konnte aber aufgrund ihrer XML-Struktur nie standardisiert werden.

Deshalb hat sich Swagger schnell zur wohl populärsten Technologie unter den API-Dokumentationen entwickelt. Genauer gesagt zur populärsten Technologie für die häufig eingesetzten REST-APIs. Swagger wurde von Reverb entwickelt, läuft aber mittlerweile herstellerneutral als Open Source unter dem Mantel der Linux Foundation bzw. über die Open API Initiative. In Zuge dessen wurde Swagger auch in OpenAPI Specification umbenannt – ist aber inoffiziell weiterhin unter dem griffigeren Namen Swagger bekannt.

In einem Vortrag im Rahmen der API Conference wurde Swagger am Beispiel von u. A. Spring Boot vorgestellt und seine Alltagsintegrierung erklärt.

Das Kernelement von Swagger ist je nach Einsatzgebiet eine JSON- oder eine YAML-Datei. Die Benutzeroberfläche, mit der man die Dokumentationen ganz leicht erstellen kann, basiert auf HTML und JavaScript. Grundsätzlich hat Swagger ein sprachneutrales und maschinenlesbares Format. Über das User-Interface lässt sich nicht nur die Dokumentation verwalten, sondern mit ihm kann Swagger zum Beispiel auch Ad-hoc-Tests durchführen.

Ein Vorteil von Swagger wird auch im umfangreichen Erweiterungsmodus sichtbar, der durch eine Kernbibliothek, dem Swagger-Core, unterstützt wird. Die Benutzeroberfläche wird Swagger UI genannt, der Codegenerator Swagger Codegen, darüber hinaus gibt es einen Swagger Editor.

Aber die größte Stärke zieht Swagger, wie viele Open-Source-Angebote, aus dem umfassenden Ökosystem von GitHub. Hier finden Entwickler Codegeneratoren für nahezu alle Programmiersprachen. Swagger dokumentiert jede Schnittstelle mit allen Informationen.

Die Dokumentationsdatei beginnt mit der Angabe der verwendeten Spezifikationsversion, dann folgen die generellen Informationen zum API, klar sortiert unter der Kategorie info. Swagger trennt auch Host, Pfad und URL-Schema und gibt sie einzeln an. Erst danach erfolgt der Mediatype für die gesamte API. Diese Aufbereitung ist wie ein komplexes Karteikartensystem.

Erst nach dieser Kategorisierung werden die Inhalte dargestellt: Pfade, Operatoren und Parameter werden mitsamt der zugehörigen Beschreibung aufbereitet. Datentypen werden extra in einem eigenen Abschnitt verwaltet. Durch das Swagger UI lässt sich das Ganze nicht nur in Textform darstellen, sondern auch grafisch visualisieren. Das ist vor allem von Vorteil, wenn direkte Testanfragen aus dem Browser gesendet werden sollen. Diese Mischung aus perfekter Dokumentation und der gleichzeitigen Möglichkeit, direkte API-Anfragen auszulösen, macht Swagger so wertvoll.

Für die Entwicklung von APIs ist eine ordentliche, verständliche Dokumentation essenziell. Nur mit ihr können die Schnittstellen von Entwicklern eingesetzt werden. Das gilt noch mehr für öffentliche APIs: ohne Dokumentation sind sie für die Community unbrauchbar, lassen sie sich nicht verbreiten und bringen keinen Erfolg.

Swagger ist die derzeit beste Möglichkeit, REST-APIs zu dokumentieren, da es nahezu alle Webservices und Informationen rund um die Schnittstelle abbilden kann. Es wächst gleichmäßig mit dem System und dokumentiert Änderungen automatisch. Das funktioniert so gut, weil Swagger die Dokumentation des REST-API direkt am Code hinterlegt.

Der Ausgangspunkt jeder API-Entwicklung ist entweder der Programmcode – Code First – oder die Schnittstellenbeschreibung – Design First. Befindet man sich in einer Entwicklung, die der Maxime Code First folgt, ist der vereinbarte Ausgangspunkt der Programmcode. Aus diesem kann Swagger direkt eine Dokumentation ableiten, die unabhängig von der verwendeten Programmiersprache und sowohl von Maschinen als auch von Menschen lesbar ist.

Auf der anderen Seite steht das Paradigma Design First. Wie bereits erwähnt sind häufig unterschiedliche Entwickler für eine Client- und Serverseite verantwortlich. Bei Design First wird die Beschreibung zuerst angefertigt. Die Codes werden anschließend einfach mit Swagger generiert. Dafür gibt es Generatoren für alle gängigen Programmiersprachen und selbst die Vorlagen können nochmals angepasst bis erweitert werden.

Swagger bietet also nahezu automatisch einen konsistenten API-Code. Sollte etwas in der manuellen Programmierung nicht stimmen, treten Kompilierungsfehler auf, die die Einbindung in ein Continuous-Integration-System automatisch sichtbar macht.

Die Vorteile von Swagger überwiegen so stark, dass man Swagger durchaus als hervorragende Standardanwendung für die Schnittstellenbeschreibung bei RESTful APIs bezeichnen kann. Wie viele andere Open-Source-Anwendungen profitiert Swagger von einer hohen Verbreitung und damit bedingt einer umfangreichen Tool-Unterstützung. Das Gremium von Swagger besteht aus Tech-Größen wie Microsoft, IBM und Google, wodurch die OpenAPI Specification nachhaltige Rückendeckung genießt – auch wenn es Alternativen gibt: Die Restful API Modelling Language (RAML) basiert beispielsweise ebenfalls auf YAML und kann sogar noch komplexere Definitionen als Swagger schaffen. Der Ersteller von RAML (Mulesoft) ist aber inzwischen selbst der OpenAPI Initiative beigetreten.

Ein kleiner Nachteil von Swagger ist die Verständlichkeit und Lesbarkeit der Dokumentation. Zwar bietet Swagger bereits ein relativ gut aufbereitetes Format, dennoch benötigt man etwas Zeit für die Einarbeitung. Dass es noch einfacher geht, beweist API Blueprint mit einer Markdown-Syntax.

Auf der Swagger-UI-Website findet man das komplette Swagger-ZIP-Paket. Nach dem Download muss entschieden werden, ob Swagger lokal oder auf einem Server betrieben werden soll.

Achtung: Wenn es lokal laufen soll, benötigt man MAMP. Der entpackte Ordner Swagger UI Master wird dann entweder ins MAMP-Verzeichnis oder auf den Server gelegt. Jetzt braucht man nur noch die URL des Servers bzw. des Localhosts im Browser aufrufen und Swagger öffnet sich automatisch und die erste API-Dokumentation startet.

Noch einfacher geht es mit der Web-Version des Swagger-Editors. Dieser lässt sich problemlos im Browser bedienen und man profitiert davon, neben dem Texteditor eine grafisch aufbereitete Fassung der Dokumentation angezeigt zu bekommen.

An diesem kurzen Auszug eines Swagger-Beispiels kann man schon den verständlichen Aufbau erkennen. Alle Informationen sind klar benannt und können unabhängig von einer Programmiersprache verstanden werden.

Anschließend lässt sich die Dokumentation direkt als YAML-Datei exportieren oder zuerst ins JSON-Format umwandeln. Das ist die Dokumentationsdatei, die im Swagger UI gelesen werden kann. Die angezeigten Inhalte zeigen zunächst die Pfade, Schnittstellen und Endpunkte. Danach kommen die Beschreibungen, Parameter sowie der Response und seine Bedeutungen. An den Endpunkten können die Ad-hoc-Tests über die Swagger Benutzeroberfläche ausgeführt werden.

Das Gute an Open Source ist, dass man die Tools kostenlos ausprobieren kann. Das gilt im Falle von Swagger für das UI und auch für sämtliche Tools. Man kann sich also selbst ein Bild von den Möglichkeiten Swaggers machen.