Swagger ist ein Opensource-Framework zur Unterstützung bei Design, Entwickelung, Test und Dokumentation von RESTful APIs.

Mit der Version 2.0 werden dazu die Module

• Swagger Editor zum Design,
• Swagger Build zum Generieren von Clients und Servern,
• Swagger UI um Dokumentieren von Schnittstellen

angeboten.

Entwicklung der Service-Dokumentation mit swagger-editor

In meinem Fall lag das RESTful API auf Serverseite schon vor. Ich wollte dieses API für Konsumenten der Schnittstelle dokumentieren. Dazu bietet sich das Javascript-basierte Module swagger-editor an.  Die Installation erfolgt einfach:

Von github.io wird das Projekt https://github.com/swagger-api/swagger-editor heruntergeladen, anschließend werden die notwendigen rpm-module mittels

$> npm install

installiert. Durch Aufruf von

$> npm start

wird dann der webbasierte Editor aufgerufen.

Darin wird die Beschreibung des RESTful-API entweder in einer JSON-Struktur oder in der YAML-Schreibweise festgelegt. Die API-Definitionen können dort interaktiv getestet werden – einfach großartig, wie schnell man dort einen Überblick über sein API bekommt.

Ist die Definition der Schnittstelle – hier einen Clients – abgeschlossen, wird diese als JSON- oder als YAML-Datei auf einem Web-Server bereitgestellt.

Bereitstellen der Service-Dokumentation in Swagger-UI

swagger-editor ist ein Editor zum Entwickeln der Service-Beschreibung. Diese Modul ist nicht geeignet, um den eigenen Service für andere zu dokumentieren – in diesem Fall sollte die Service-Schnittstelle nicht mehr veränderbar sein.

Genau diese Zweck erfüllt das Modul swagger-ui, welches man ebenfalls von github.io herunterladen kann.

Hat man dieses Modul heruntergeladen, so muss man noch den Verweis auf die zu testenden Schnittstelle eintragen.

Dazu ändert man in dist/index.html den Verweis auf die weiter ob bereitgestellte eigene swagger.json -Datei.

Anschliessend lädt man den ganzen swagger-ui-Ordner auf den gewünschten Web-Server.