12. August 2016 | 2 min lesezeit

Swagger UI integriert

REST-Schnittstellen können via Swagger spezifiziert und dokumentiert werden. Doch die beste Dokumentation ist überflüssig, wenn es keine Leser gibt. Eine Swagger-Spezifikation benötigt für das Lesen bzw. Darstellen der Dokumentation ein weiteres Tool, Abhilfe schafft hier die Swagger UI. Zusätzlich bietet die Swagger UI die Möglichkeit eine Schnittstelle direkt zu testen. Eine allgemeine Einführung zum Thema kann im Artikel Dreh den Swag auf! nachgelesen werden. Dieser Artikel zeigt wie die Swagger UI in ein WebArchiv integriert werden kann, damit das Tool immer nutzbar ist.

Sollte noch keine swagger.json Datei vorliegen, wird der Artikel swagger on the fly zur Einrichtung der automatischen Generierung empfohlen.

Neben der Darstellung der API Dokumentation kann mit Hilfe der Swagger UI die API direkt im Browser ausprobiert und das Ergebnis angezeigt werden. Dadurch lässt sich die Einstiegshürde für Entwickler der Schnittstelle noch weiter verringern. Nachfolgend ein Screenshot der Swagger UI und dessen Darstellung einer vorhandenen Spezifikation:

Swagger UI

Zum Ausprobieren stellt das Swagger Team eine Beispielschnittstelle in Form eines PetStore zur Verfügung: http://petstore.swagger.io/

Swagger UI ins Deployment integrieren

Die Dateien der Swagger UI werden vom Swagger Team nicht direkt als jar-Datei zur Verfügung gestellt. Hier kommt das Projekt WebJars ins Spiel, welches auf Maven Central entsprechende jar-Dateien zur Verfügung stellt.

Damit die Dateien auch in dem deploybaren war-Archiv landen, wird das Maven Dependency Plugin zum Entpacken und Kopieren eingesetzt. Die Integration kann beispielsweise wie folgt aussehen:

Im ersten Schritt wird die Datei entpackt und im zweiten Schritt wird der Inhalt kopiert. Die Swagger UI würde via /<Context Path>/swagger-ui/index.html erreichbar sein.

Swagger UI Standard-URL ersetzen

Nach dem Deployment des Archive auf einen Webcontainer zeigt die Swagger-UI die URL http://petstore.swagger.io/v2/swagger.json.

Swagger UI Petstore

In der Regel soll hier aber die eigene json-Datei angezeigt werden, dazu muss die index.html nach dem Entpacken automatisch „korrigiert“ werden.
Dafür kann ein weiteres Maven Plugin genutzt werden:

Anschließend wird das Projekt neu gebaut und als neue URL wird der definierte Wert angezeigt.

Viel Spaß beim Erkunden und Ausprobieren der API.


Keine Kommentare

Kontakt

OPEN KNOWLEDGE GmbH

Standort Oldenburg:
Poststraße 1, 26122 Oldenburg

Standort Essen:
II. Hagen 7, 45127 Essen