14. Dezember 2015 | 4 min lesezeit

Dreh den Swag auf!

Neben dem Schreiben von Tests ist sicherlich die Erstellung von Dokumentation eines der unbeliebtesten Aufgaben, die sich ein Entwickler vorstellen kann. Gerade bei REST-Schnittstellen wird die Notwendigkeit oft unterschätzt. Dabei lässt sich die Dokumentation direkt aus dem Code generieren und ist damit ständig aktuell.

Die Schnittstelle eines RESTful Services, stellt eine öffentliche Systemgrenze dar, die von Dritten genutzt werden soll. Trotz des Anspruchs lesbare und verständliche APIs zu entwicklen, bedarf es i.d.R. einer technischen und fachlichen Beschreibung der Schnittstellensignatur, d.h. eine aussagekräftige und aktuelle Dokumentation, um dieses auch nutzen zu können. Ein gutes API Design und eine gute Dokumentation erfordern daher (viel) Zeit und Disziplin. Leider ist es damit oftmals schnell vorbei, wenn Druck und Arbeitsbelastung im Projekt ansteigen. An dieser Stelle setzt Swagger an.

Swagger erlaubt die Beschreibung von RESTful Services über eine formale Spezifikation im JSON oder YAML Format, der Swagger-Datei, die sowohl für Menschen als auch für Maschinen lesbar ist. Das enthaltene Toolset unterstützt bei der Definition dieser Spezifikation und erlaubt darüber hinaus die Generierung von Servern und Clients in zahlreichen Zielsprachen (Java, JavaScript, Ruby, Scala, …). Noch wertvoller ist Swagger aber in Kombination mit dem swagger-maven-plugin, das die Swagger-Datei im Rahmen des Build-Jobs generiert.

Befindet man sich in der Frühphase eines Projekts und darf auf der grünen Wiese beginnen, dann kann Swagger auch für das Design der Schnittstellen genutzt werden (Contract-First Ansatz). In diesem Fall hat der Entwickler die Möglichkeit aus den Vollen zu schöpfen. Er spezifiziert die Schnittstelle im Swagger Editor und nutzt die Swagger-Datei, um mittels Swagger-Codegen Server- und Client-Code in der gewünschten Zielsprache zu generieren.

In den meisten Fällen kommt aber der Code-First Ansatz zum Tragen, bei dem Swagger zur Dokumentation einer bestehenden Schnittstelle genutzt wird. Hierfür bietet Swagger einen Satz eigener Annotationen, um die API Klasse und ihre öffentliche Methoden um zusätzliche Metainformationen zu ergänzen, wie am Beispiel der CustomerResource nachvollzogen werden kann.

Um die Swagger Annotation nutzen zu können, muss die Abhängigkeit swagger-jaxrs zum Build-Path hinzugefügt werden.

Über das maven-swagger-plugin wird beim Kompilieren die Swagger-Datei (swagger.json) erzeugt und in einem eigenen Verzeichnis (swaggerDirectory) abgelegt. Dazu müssen alle relevanten API Klassen mit Swagger Annotationen ergänzt und in der Plugin-Konfiguration der Klassenpfad der Resource oder das zugehörige Package definiert werden. REST Resourcen ohne Swagger Annotationen werden (leider) ignoriert.

Die Swagger-Datei für die oben gezeigte CustomerResource sieht dann wie folgt aus.

Schaut man sich die Swagger-Datei genauer an, mag der erste Eindruck ernüchternd sein. Die formale Spezifikation ist nicht unbedingt lesbarer als der zugehörige Java Code. Doch die plattformunabhängige Form der Spezifikation bietet die Basis für eine Weiterverarbeitung auch außerhalb von Java.

So kann die Swagger-Datei nicht nur zur Generierung von Client/Server Code genutzt, sondern auch über ein beliebiges Webinterface öffentlich zugänglich gemacht werden, so dass bspw. externe Dienste diese im Frontend über weitere Tools wie Swagger JS, swagger-angular-client, swagger-node-client geeignet anbinden können.

Um die Lesbarkeit zu verbessern, kann erneut auf das swagger-maven-plugin zurück gegriffen werden. Mit der Angabe der zusätzlichen Parameter templatePath und outputPath und mit Hilfe der Template Engine Handlebars wird die Generierung eines ansprechenden und lesbaren statischen Dokuments ermöglicht.

Einen Schritt weiter geht SwaggerUI,  mit dem es möglich ist, aus der Spezifikation eine interaktive Dokumentation mit HTML, CSS und JavaScript bereitzustellen. Die verfügbare Distribution kann nach der Konfiguration des Spezifikationspfades direkt genutzt werden, was bei der CustomerResource die folgende Ansicht ergibt.

swagger_ui

Über die beschriebenen Ressourcen können direkt Requests (auch fehlerhafte) gegen die Schnittstelle einer Testinstanz abgesetzt werden. Sie hat den großen Vorteil neben der Dokumenation auch als Spielwiese für API Consumer oder auch Stakeholder zu dienen, die auf einfache Weise ein Verständnis für die Möglichkeiten der Schnittstelle aufbauen wollen.

Swagger bietet sehr viele nützliche Tools, um den Aufwand beim Design und insbesondere der Dokumentation einer RESTful API, so gering wie möglich zu halten. Die Technologie unabhängige Spezifikation lässt sich sehr einfach in unterschiedliche Technologie Stacks, wie sie bspw. innerhalb einer Anwendungslandschaft mit Microservices auftreten können, integrieren. Gerade im stetigen Wandel der heutigen IT ist die Unabhängigkeit ein gutes Argument Swagger auszuprobieren.


Keine Kommentare

Kontakt

OPEN KNOWLEDGE GmbH

Standort Oldenburg:
Poststraße 1, 26122 Oldenburg

Standort Essen:
II. Hagen 7, 45127 Essen