© Ysbrand Cosijn, 123RF

Ein REST-API nützt einem Entwickler vor allem dann, wenn der API-Anbieter die Methoden ausführlich dokumentiert. Genau dabei hilft das Toolpaket Swagger. Dessen Werkzeuge generieren nicht nur halbautomatisch eine API-Referenz, sondern auch ein passendes Client-SDK für zahlreiche Programmiersprachen.

Webanwendungen bieten für externe Nutzung ihrer Dienste oft eine so genannte REST-Schnittstelle an. Diese sprechen Entwickler dann aus ihren eigenen Programmen heraus an, indem sie über spezielle URLs und HTTP-Anfragen darauf zugreifen. Das setzt voraus, dass das REST-API möglichst vollständig dokumentiert ist. Noch besser wäre meist eine Bibliothek, die einen etwas komfortableren Zugriff auf den Dienst ermöglicht und es somit vereinfacht, Clientprogramme zu schreiben.

Für den Hersteller der Webanwendung ist allerdings beides mit Arbeit verbunden: Er muss die Dokumentation und die Clientbibliothek nicht nur entwickeln, sondern bei jeder Schnittstellenänderung auch aktualisieren. Beides automatisiert die Wunderwaffe Swagger [1]. Dieser Begriff (englisch für “todschick”) verweist auf eine Spezifikation [2] sowie mehrere Tools, die zu einem REST-API eine interaktive Dokumentation erzeugen und auf Wunsch sogar ein kleines Software Development Kit für Clientprogramme generieren.

Aufgabenteilung

Das klingt zunächst kompliziert, erweist sich in der Praxis jedoch als bemerkenswert simpel [3]: Zunächst beschreibt der Entwickler das Funktionsangebot seines REST-API in einer Textdatei. Die schreibt er entweder per Hand oder lässt sie automatisch aus dem Quellcode der Webanwendung generieren.

Letzteres setzt voraus, dass eines der von den Swagger-Tools unterstützten Frameworks zum Einsatz kommt. Dazu zählen Jax-RS [4] und Node.js [5]. In jedem Fall greifen dann zwei Tools nach der API-Beschreibung und produzieren daraus eine komplette API-Referenz sowie ein passendes SDK. Integriert der Entwickler die Swagger-Tools in den Buildprozess, bleiben die Dokumentation und das Client-SDK automatisch auf dem aktuellen Stand.

Das von der Firma Smartbear [6] entwickelte Swagger besteht zum Teil aus einer recht umfangreichen Spezifikation [2]. Sie gibt detailliert vor, wie der Entwickler sein REST-API in der Textdatei aufschreiben muss. Die komplette Swagger-Spezifikation hat Smartbear am 1. Januar 2016 der Open API Initiative [7] übergeben, hinter der wiederum die Linux Foundation steht. Dabei erhielt die Spezifikation den neuen Namen Open API Specification [8]. Da ihr die Swagger-Spezifikation in Version 2.0 zugrunde liegt, trägt auch die Open API Specification diese Versionsnummer.

Hammer und Meißel

Rund um die Spezifikation hat Smartbear eine Reihe nützlicher Werkzeuge veröffentlicht. Dazu zählt zunächst der Swagger Editor [9], mit dem User die Beschreibung des REST-API recht komfortabel anlegen und bearbeiten. Er bringt nicht nur Syntax Highlighting mit, sondern klappert die Beschreibung auch auf Syntaxfehler gegen die Swagger-Spezifikation ab. Fehler ganz allgemein hebt er farblich hervor, gibt Formatierungstipps und zeigt eine Vorschau der späteren Dokumentation an.

Eines der wichtigsten Tools im Bunde ist das Swagger UI. Es erzeugt aus der Beschreibung des REST-API eine praktische interaktive HTML-Dokumentation. Benutzer rufen auf Wunsch sogar direkt aus der Dokumentation heraus die Funktionen des Dienstes auf.

Wie solch eine Dokumentation aussieht, demonstrieren die Swagger-Macher auf ihrer Website: Dort stellen sie eine fiktive Online-Tierhandlung bereit, die der User über eine REST-Schnittstelle steuert. Dank der mit Swagger erzeugten API-Referenz [10] sehen sie nicht nur die vom Onlineshop angebotenen Funktionen, sondern ergänzen mit wenigen Mausklicks unter anderem neue Tiere (Abbildung 1). Das Swagger UI ist vollständig in HTML, CSS und Javascript geschrieben, Entwickler passen die Optik der Dokumentation recht einfach an ihre Wünsche an (Abbildung 2, [11]).

Abbildung 1: Auf ihren Seiten bieten die Swagger-Macher einen (fiktiven) Onlineshop mit einer REST-Schnittstelle an. Ihren Aufbau beschreibt die von Swagger erzeugte Dokumentation.

Abbildung 2: Auch die Dokumentation des REST-API der Watson Developer Cloud entsteht mit Hilfe von Swagger und gibt Interessierten so einen ersten Eindruck von den Ergebnissen.

Das Werkzeug Swagger Codegen [12] generiert schließlich aus der Beschreibung des REST-API ein komplettes SDK, mit dem Entwickler Clientanwendungen für den Dienst schreiben. Die SDKs erzeugt es dabei für verschiedene Programmiersprachen – angefangen bei Java, Python, PHP und Ruby bis hin zu Scala. Das Komplettpaket aus der Swagger-Spezifikation und den zugehörigen Tools bezeichnen die Swagger-Macher gerne als API-Framework.

Alle genannten Werkzeuge unterstehen der liberalen Apache-2.0-Lizenz. Das komplette Swagger-Framework kommt nach Angaben von Smartbear unter anderem bei Getty Images, Microsoft und Paypal zum Einsatz (siehe auch Kasten “Swagger in freier Wildbahn”).

Bauplan

Im Swagger Editor lässt sich das REST-API komfortabel beschreiben. Bei ihm handelt es sich um eine Webanwendung, die einen Webserver voraussetzt. Wer sich die Installation sparen möchte, nutzt den Editor direkt auf der Swagger-Homepage (Abbildung 3, [9]). Betreiber eines (lokalen) Webservers laden sich zunächst unter [15] das zum aktuellen Swagger Editor passende Archiv »swagger-editor.zip« herunter (nicht den Sourcecode). Dieses entpacken sie und schieben dann den kompletten Inhalt des Verzeichnisses »swagger-editor« auf den Webserver oder in das dortige »DocumentRoot« -Verzeichnis.

Abbildung 3: Im Swagger Editor beschreibt der Entwickler der Webanwendung komfortabel das REST-API. Im Beispiel geht es um den (fiktiven) Swagger Petstore, er sich mit Tieren ausstatten lässt.

Wer nicht extra einen Webserver installieren will, greift wahlweise auch zum Node.js-Modul »http-server« . Dies installieren und starten unter Ubuntu die Befehle aus Listing 1. Sie holen zudem den Swagger Editor in der bei Redaktionsschluss aktuellen Version 2.10.1 auf die Platte. Nach der Befehlsorgie erreicht der Nutzer den Editor unter »http://localhost:8080« . Docker-Anhänger fahren den Editor auch mit folgenden zwei Docker-Befehlen hoch:

docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/ swagger-editor

In jedem Fall landet der Nutzer anschließend in der Benutzeroberfläche aus Abbildung 3. Auf der linken Seite tippt er die Beschreibung des REST-API ein, auf der rechten erscheint entweder parallel eine Vorschau der Dokumentation oder eine Fehlermeldung.

01 sudo apt-get install npm nodejs-legacy
02 sudo npm install -g http-server
03 wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip
04 unzip swagger-editor.zip
05 http-server swagger-editor

Standardmäßig zeigt der Editor ein etwas komplexeres Beispiel an, unter »File | Open Example« sind aber auch ein paar einfachere zu finden. Das Beispiel »minimal.yaml« eignet sich gut als Skelett für eigene Beschreibungen, es ist noch etwas kompakter als das per »File | New« erzeugte Grundgerüst.

Den Aufbau des REST-API notiert der Entwickler entweder im Json- oder Yaml-Format. Letzteres ist etwas einfacher zu lesen, nutzt aber Einrückungen, um den Code zu strukturieren. Listing 2 zeigt ein einfaches Beispiel für eine API-Beschreibung in Yaml, das wiederum auf dem Beispiel »echo.yaml« basiert. Es beschreibt die REST-Schnittstelle des unter [16] erreichbaren Echo-Dienstes. Der liefert einfach alle an ihn gesendeten Informationen wieder an den Absender zurück.

Eingerückter Zeichensalat

In der Zeile 1 von Listing 2 steht hinter »swagger« die Versionsnummer der zugrunde liegenden Swagger-Spezifikation. Der anschließende »info« -Block liefert einige Basisinformationen. Hinter »title« erscheint zunächst der Name des Dienstes. Er taucht später dick und fett als Überschrift über der Dokumentation auf (in Abbildung 3 lautet er »Swagger Petstore (Simple)« ).

01 swagger: '2.0'
02 info:
03   title: Echo-Beispiel
04   version: 1.0.0
05   description: |
06     #### Liefert jede URL, Methode, Parameter und Header zurück
07     Der Echo-Server liefert **jeden** Wert einfach zurück.
08 schemes:
09   - http
10 host: mazimi-prod.apigee.net
11 basePath: /echo
12 paths:
13   /test:
14     get:
15       responses:
16         200:
17           description: Echo per GET-Methode
18     post:
19       responses:
20         200:
21           description: Echo per POST-Methode
22       parameters:
23         - name: name
24           in: formData
25           description: Ein Beispiel-Parameter
26           type: string

Das von [16] angebotene API liegt in der Version 1.0.0 vor, was wiederum der Eintrag in Zeile 4 verrät. Dahinter folgt also weder die Version des Dienstes noch die Versionsnummer der Swagger-Spezifikation. Die mit »description« beginnende Zeile beschreibt in kurzen Worten den Dienst. Die Zeile hinter »####« sowie der Text zwischen »**« erscheinen später fett gedruckt.

Die vom Dienst verwendeten Transferprotokolle stehen hinter »schemes« , der Echo-Dienst nimmt nur HTTP-Anfragen entgegen. Hinter »host« folgen der Hostname oder die IP-Adresse des Dienstes jeweils ohne weitere Anhängsel oder Präfixe. Erlaubt ist nur noch eine Portangabe. Der Basispfad zum Dienst folgt separat hinter »basePath« . Die dortige Angabe gibt der Entwickler relativ zum Hostnamen mit vorangestelltem Schrägstrich an. Im Beispiel steht der Echo-Dienst somit unter [16] bereit.

Welche Ressourcen es gibt und welche Operationen Clients auf ihnen ausführen dürfen, legt der Block unterhalb von »paths« fest. Im Exempel gibt es nur eine Ressource unter »/test« . Auf ihr lassen sich die Methoden »GET« und »POST« ausführen. »GET« liefert als Antwort stets den Statuscode 200 (“erfolgreich”). Hinter »description« folgt eine möglichst kurze, aber aussagekräftige Beschreibung der Operation.

Die »POST« -Methode besitzt zusätzlich noch einen »parameter« . Dieser trägt den Namen »name« und ist ein String, was »type« festlegt. Wie der Dienst den Parameter überträgt, steht hinter »in« , mögliche Werte sind »query« , »header« , »path« , »formData« und »body« .

Die aus dieser Beschreibung vom Editor erzeugte Dokumentation zeigt Abbildung 4. Über »Try this operation« probiert der Entwickler die jeweilige Methode auch direkt aus. Im Editor klappt das aber nur dann, wenn der Dienst einen so genannten Cross Origin Call erlaubt. Der ist aus Sicherheitsgründen meist nicht gestattet, wodurch die Anfrage fehlschlägt.

Listing 2.” width=”300″ height=”248″ /> Abbildung 4: Der Editor erzeugt hier auf der rechten Seite die Dokumentation zur Beschreibung aus Listing 2.

UI in Action

Die fertige Beschreibung lädt sich der Entwickler jetzt herunter – entweder im Yaml-Format per »File | Download YAML« oder als Json-Datei via »File | Download JSON« . Anschließend installiert er das Swagger UI und setzt es auf die Json- beziehungsweise Yaml-Datei an.

Dazu lädt er sich zunächst unter [17] das aktuelle »Source-Code« -Archiv des Swagger UI herunter. Wenn er es entpackt, purzeln mehrere Verzeichnisse heraus. Mit dem Browser öffnet er im Unterordner »dist« die Datei »index.html« . Wer die Dokumentation öffentlich bereitstellen möchte, muss dafür lediglich den Inhalt des Unterordners »dist« auf den Webserver beziehungsweise in das entsprechende »DocumentRoot« -Verzeichnis schieben.

In jedem Fall präsentiert das im Browser erscheinende Swagger UI zunächst die Beispieldokumentation für die fiktive Online-Tierhandlung (wie sie auch Abbildung 1 zeigt). Damit das UI die Dokumentation für das eigene REST-API anzeigt, kopiert der Anwender die mit dem Swagger Editor erstellte Datei in das »dist« -Verzeichnis.

Dort wiederum öffnet er die Datei »index.html« in einem Texteditor und tauscht im oberen Teil hinter »url=« die Angabe »http://petstore.swagger.io/v2/swagger.jsonurl« gegen den Dateinamen der Json- beziehungsweise Yaml-Datei aus. Wer das Swagger UI offline nutzt und die »index.html« direkt im Browser öffnet, muss den kompletten Pfad zur Datei hinterlegen, etwa »/home/tim/swagger-ui/dist/swagger.yaml« . Das Swagger UI greift sich dann künftig diese Datei und generiert daraus die passende Dokumentation. Für die Beschreibung aus Listing 2 sieht die API-Referenz dann wie in Abbildung 5 aus.

Listing 2.” width=”300″ height=”189″ /> Abbildung 5: Das Swagger UI zeigt die Dokumentation zur REST-Schnittstelle aus Listing 2.

Das Swagger UI präsentiert nicht nur die Dokumentation, sondern versucht auch immer, die Beschreibung gegen die Swagger-Spezifikation zu validieren. Das gelingt aber nur, wenn die Beschreibung öffentlich zugänglich ist. Kommt sie nur offline oder in einem Intranet zum Einsatz, erscheint rechts unten in der Ecke die rote Meldung »Error« . Wer sie loswerden möchte, muss in den Quellcode des Swagger UI eingreifen.

Sprachgewandte Klientel

Der Swagger Editor kann aus der Beschreibung direkt ein Client-SDK erzeugen. Dazu klappt der Entwickler das Menü »Generate Client« auf und wählt die gewünschte Programmiersprache. Er erhält ein Zip-Archiv mit allen für die Client-Entwicklung notwendigen Dateien, darunter auch die »README.md« , die kurz beschreibt, wie er das SDK einrichtet und in Betrieb nimmt. Die erzeugte Dokumentation aus Abbildung 5 gehört explizit nicht zum SDK.

Alternativ zum Editor lässt sich das SDK auch mit Swagger Codegen [18] erzeugen. Dieses Kommandozeilentool setzt mindestens Java 7 voraus. Ist ein entsprechendes JRE installiert, holt der Nutzer sich die fertige Version 2.1.6 von Codegen mit dem folgenden Bandwurmbefehl:

wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.1.6/swagger-codegen-cli-2.1.6.jar -O  swagger-codegen-cli.jar

Anschließend liefert

java -jar swagger-codegen-cli.jar help

eine Liste mit allen möglichen Kommandozeilen-Optionen. Möchte ein Entwickler herausfinden, welche Programmiersprachen Codegen unterstützt, erreicht er das über den Befehl:

java -jar swagger-codegen-cli.jar langs

In der Liste mit den Kürzeln sucht der Anwender sich die gewünschte Programmiersprache heraus und ruft damit dann Swagger Codegen auf. Das folgende Beispiel würde ein SDK für Python erzeugen, wobei die Beschreibung des REST-API in der Datei »swagger.yaml« liegt und das fertige SDK im Verzeichnis »meinsdk« landet:

java -jar swagger-codegen-cli.jar generate -l python -i swagger.yaml -o meinsdk

Für Java-Entwickler steht nicht zuletzt noch ein Swagger Core [19] genanntes Paket mit mehreren Bibliotheken bereit, die Swagger-Beschreibungen lesen und erzeugen. Der Swagger Editor generiert zudem aus der API-Beschreibung ein Grundgerüst für eine passende Serveranwendung. Dazu öffnet der Entwickler das Menü »Generate Server« und wählt das bevorzugte Framework aus. Swagger hilft also auch dabei, ein REST-API aufzubauen.

Fazit

Die vom Swagger UI erzeugten Seiten sehen recht karg aus und stehen zumindest optisch immer neben der restlichen Dokumentation. Die Integration in eine vorhandene Onlinehilfe nebst passendem Design erfordert größere Eingriffe. Der Informationsgehalt hängt zudem maßgeblich davon ab, wie ausführlich der Anbieter seinen Dienst in der API-Beschreibung vorstellt. Nicht zuletzt funktioniert die Bedienung der Swagger-UI-Seiten nicht immer selbsterklärend.

Im Gegenzug kostet der Einsatz von Swagger kaum Mehrarbeit, erleichtert aber Anwendern oder anderen Entwicklern den Zugriff auf das REST-API. Wer die Werkzeuge geschickt in seinen Buildprozess integriert, erhält sogar eine stets aktuelle Dokumentation samt Client-SDK. Umgekehrt erzeugen sich Programmierer mit Swagger schnell ein Client-SDK zu einem fremden REST-API und sparen so zumindest Tipparbeit. Ein Blick auf Swagger und die zugehörigen Tools kann sich folglich für alle Seiten lohnen.