REST-APIs mit Node.js und Swagger

Inhaltsverzeichnis

Bei RAML, API Blueprint und Swagger handelt es sich um Beschreibungssprachen für REST-APIs, wobei JSON oder YAML als Formate zum Einsatz kommen. Grundsätzlich hat die Verwendung einer API-Beschreibungssprache einige Vorteile: Zum einen lässt sich über sie exakt definieren, wie eine API auszusehen hat, beispielsweise welche Endpunkte angeboten werden, welche HTTP-Methoden die Schnittstelle unterstützt, wie Requests auszusehen haben, welche Parameter erwartet werden, welchen Datentyp die Parameter haben, wie Responses aufgebaut sind und vieles mehr. Auf diese Weise macht man sich zum einen von vornherein mehr Gedanken über die zu entwickelnde API, was sich wiederum positiv auf die Stabilität selbiger auswirkt. Zum anderen können API-Spezifikationen, die in einer der genannten Beschreibungssprachen definiert wurden, anschließend als Grundlage für das Erstellen von Tests oder für die automatische Codegenerierung dienen.

Welche der genannten Beschreibungssprachen dabei die "Beste" ist, lässt sich nicht pauschal beantworten und soll daher nicht das Thema sein. Wer sich ausführlicher mit ihren Details befassen möchte, dem seien die guten Dokumentationen samt Einsteigertutorials auf den jeweiligen Homepages empfohlen. Wer hingegen auf der Suche nach den Unterschieden zwischen den Beschreibungssprachen ist, wird in einer Reihe von Artikeln fündig.

Der folgende Artikel befasst sich speziell mit dem swagger-Tool, einem offiziellen Node.js-Package vom Swagger-Team, das die Entwicklung von REST-APIs (im Swagger-Format) unter Node.js erleichtern soll.

Installation und Erstellen einer API

swagger lässt sich mit dem Node.js Package Manager (NPM) über folgenden Befehl global installieren:

$ npm install -g swagger
 

Anschließend lässt sich das Tool auf der Kommandozeile mit swagger verwenden, wobei weitere Kommandos zur Verfügung stehen, auf die gleich noch im Detail eingegangen wird. Ergänzende Informationen finden sich in der offiziellen Dokumentation.

• swagger: ermöglicht die Ausgabe einer Hilfe (swagger -h) und der Versionsnummer (swagger -v).
• swagger project create: erstellt ein neues Projekt.
• swagger project start: startet ein Projekt.
• swagger project verify: überprüft die aktuelle API-Spezifikation und gibt eventuelle Fehler und Warnungen aus.
• swagger project edit: öffnet ein Projekt im Swagger Editor.
• swagger project open: öffnet den Standardbrowser als Client für die API.
• swagger project test: führt Unit-Tests gegen die API aus.
• swagger docs: öffnet die offizielle OpenAPI Specification, die übrigens aus den Ideen von Swagger hervorgegangen ist.

Um ein neues Projekt zu erzeugen, verwendet man den Befehl swagger project create, wobei als Parameter der Name des Projekts zu übergeben ist:

$ swagger project create helloworld
 

Im anschließenden Auswahldialog lässt sich wählen, welches Web-Framework zu verwenden ist. Zur Verfügung stehen Connect, Express, Hapi, Restify und Sails. Hat man sich für ein Framework entschieden, stößt das Tool den Scaffolding-Prozess an und erzeugt ein komplettes Node.js-Projekt, dessen Struktur (für Express) wie folgt aussieht:

$ cd helloworld
$ tree -L 2
.
+-- README.md
+-- api
¦   +-- controllers
¦   +-- helpers
¦   +-- mocks
¦   +-- swagger
+-- app.js
+-- config
¦   +-- README.md
¦   +-- default.yaml
+-- node_modules
¦   +-- ...
+-- package.json
+-- test
¦   +-- api
+-- tree.txt

Folgende Dateien und Verzeichnisse sind dabei erwähnenswert:

• api/controllers/: enthält die Funktionen, die einzelne in der API definierten Routen anstoßen
• api/helpers/: dient als Verzeichnis für Helferdateien
• api/mocks/: dient als Verzeichnis für Controller-Attrappen
• api/swagger/: enthält die Swagger-API-Spezifikation (standardmäßig im YAML-Format)
• config/: enthält Konfigurationsdateien
• node_modules/: enthält die Node.js-Packages, die als Abhängigkeiten benötigt werden
• test/: enthält Unit-Tests, die mittels supertest die API überprüfen
• app.js: enthält den Startpunkt der API-Implementierung

Um das generierte Projekt zu starten, führt man einfach folgenden Befehl aus:

$ swagger project start
 

Das wiederum startet im Hintergrund einen HTTP-Server (im Beispiel einen, der Express nutzt) und stellt die API unter http://localhost:10010/ zur Verfügung. Zu Anfang enthält die API lediglich eine Route mit Namen hello, der man einen Parameter name übergeben kann und als Antwort eine entsprechende "Hello"-Begrüßung erhält:

Starting: /Users/ackermann/workspaces/helloworld/app.js...
  project started here: http://localhost:10010/
  project will restart on changes.
  to restart at any time, enter `rs`
try this:
curl http://127.0.0.1:10010/hello?name=Scott

Editieren und Testen der API

Besonders nützlich bei der Entwicklung einer Swagger-API-Spezifikation ist der Swagger Editor, der sowohl zum Download als auch als Online-Service zur Verfügung steht. Das Praktische: beim Anlegen des Projektes über swagger project create helloworld wurde der Editor als Abhängigkeit heruntergeladen und lässt sich daher lokal starten. Den folgenden Befehl sollte man dabei in einem zweiten Tab parallel zur gestarteten Anwendung aufrufen:

$ swagger project edit
 

Wie in folgender Abbildung zu sehen ist, teilt sich der Editor in zwei Bereiche: auf der linken Seite befindet sich der eigentliche Editor, auf der rechten eine gerenderte HTML-Vorschau. Der Editor beherrscht Syntax-Highlighting und kann syntaktische und semantische Fehler erkennen, beispielsweise wenn er referenzierte Komponenten (dazu später mehr) nicht findet.

Alle Änderungen, die man nun im Editorbereich an der API-Spezifikation vornimmt, erscheinen direkt im Vorschaubereich. Aber nicht nur das: das Programm speichert die Änderungen auch direkt in der lokalen API-Datei, sodass man sie nicht händisch in den Editor der Wahl kopieren muss.

Für das Testen einer API verwendet swagger das Tool supertest, wobei als Assertion-Bibliothek das beliebte should zum Einsatz kommt.

Die Tests lassen sich entweder mit dem Befehl swagger project test ausführen oder alternativ als Shortcut per npm test. Für die generierte Beispiel-API sieht die Ausgabe der Tests beispielsweise wie folgt aus:

$ swagger project test
try this:
curl http://127.0.0.1:10010/hello?name=Scott
  controllers
    hello_world
      GET /hello
        ✓ should return a default string
        ✓ should accept a name parameter