6. Juli 2016 | 4 min lesezeit

swagger on the fly

Beim Design einer REST API gelten ähnliche Regeln wie für Clean Code – Lesbarkeit und einfach Verständlichkeit sollten an erster Stelle stehen, um die Nutzung der API so einfach wie möglich zu gestalten. Eine gute wie aktuelle Dokumentation ist hierfür die Voraussetzung (vgl. vorherigen Artikel Dreh den Swag auf!). Und das Beste ist – sie lässt sich mit Swagger on the fly generieren. In diesem Artikel wird die automatische Generierung der Swagger Spezifikation und Bereitstellung mit einem Application Server beschrieben.

Die automatische Generierung der Swagger Spezifikation soll im Zusammenspiel mit dem WildFly Application Server (v8.2.0) und der JAX-RS Implementierung RESTeasy gezeigt werden. Um die Swagger Spezifikation für die REST API erstellen und generieren zu können, muss die aus dem vorherigen Artikel bekannte Dependency „swagger-jaxrs“ zur Liste der Abhängigkeiten hinzugefügt werden. Die entsprechenden Swagger Annotationen sind auch in der Dependency enthalten:

Nach dem Einbinden der Abhängigkeit kann der Code (Code First Ansatz) mit den Swagger Annotationen versehen werden. Ein Beispiel kann im vorherigen Artikel angesehen werden oder auf der Wikiseite zu den Swagger Annotationen angesehen werden. Das Ergebnis könnte dann wie folgt aussehen (Annotationen sind rot umrandet):

CustomerResource mit Swagger Annotationen

Die Dokumentation auf Basis der Annotation muss für jede REST Klasse durchgeführt werden. Damit eine Klasse in der Swagger Spezifikation erscheint, reicht die @Api Annotation. Es empfiehlt sich, die Methoden mit der @ApiOperation sowie die Parameter zu beschreiben.

Provider

Damit die Spezifikation automatisch generiert werden kann, muss der Generator die Klassen kennen. Provider bezeichnen in RESTEasy eine Klasse zur Verarbeitung von REST Aktionen. Dies können Schnittstellen nach außen, aber auch Klassen zum Verarbeiten von Nachrichten, sein. Swagger bringt Provider mit, um die Spezifikation nach außen zur Verfügung zu stellen.

In diesem Schritt werden die Swagger Provider registriert. Dies kann auf verschiedenen Wegen erfolgen und ist davon abhängig, wie in der vorhandenen Anwendung die Schnittstellen registriert wurden.

Die Manuelle Registrierung erfordert ein Hinzufügen aller Provider Klassen für RESTEasy in der web.xml. Durch die Automatische Registrierung ist es möglich, dass RESTEasy beim Hochfahren automatisch nach allen Klassen mit @Provider sucht und registriert. Die Erweiterung der Application Klasse erfordert eine Liste aller Provider Klassen und diese müssen um die Swagger Provider Klassen erweitert werden.

Konfiguration der Spezifikation

Eine generierte Spezifikation würde jetzt die Standardwerte nutzen. Mit der Konfiguration können Name, Basisurl und weitere Attribute beeinflusst werden. Hier bietet Swagger verschiedene Wege an.

Die Konfiguration via web.xml bietet die Möglichkeit alle Parameter zur Beschreibung der API in die web.xml auszulagern und diese ggf. im Build Prozess mit Maven automatisch setzen zu lassen. Im Gegensatz zur web.xml Variante wird bei der Konfiguration via BeanConfig innerhalb einer Klasse die Konfiguration vorgenommen.

Der Artikel nutzt die Variante der BeanConfig in einem Servlet. Eine beispielhafte Implementierung des Servlets wäre wie folgt:

Über die Methode setResourcePackage wird die Wurzel, von der gescannt werden soll, angegeben. Das setScan sorgt dafür, dass automatisch beim Hochfahren des Servlets gescannt wird und setPrettyPrint formatiert die Ausgabe der API Spezifikation.
Mehr Details zu den verschiedenen Konfigurationsparameter sind in der Swagger Wiki verfügbar.

Für die Registrierung des Swagger Servlets muss in die web.xml das Folgende eingetragen werden:

Die Präsentation

War die Konfiguration erfolgreich, kann die automatisch generierte Spezifikation via http://localhost/Context Path/swagger.json abgerufen werden. Es besteht die Möglichkeit mit Hilfe der Dateiendung das Format auszuwählen.

Unterstützt werden JSON und YAML. Für YAML wird die URL mit swagger.yaml aufgerufen werden.

Wichtig: Es ist zu beachten, dass hiermit auch empfindliche Details über die API für jeden verfügbar gemacht werden können und somit die Möglichkeit für Brute Force oder ähnliche Angriffe steigt!
Eine entsprechende Security-Konfiguration ist für öffentlich zugängliche APIs empfehlenswert, siehe Web Content Security Constraints. Handelt es sich um eine interne API sollte die Generierung der Spezifikation für die Produktionsumgebung nicht registriert werden.

JAXB Annotationen

Zum Abschluss wollen wir noch einen Sonderfall betrachten. Werden zum Mapping JAXB Annotationen eingesetzt (Beispiel XmlElement oder XmlAttribute) ist die Registrierung des JaxbAnnotationModule im Swagger Servlet erforderlich. Hierbei muss beachtet werden, dass es noch keine vollständige Unterstützung aller Möglichkeiten der JAXB Annotationen gibt. Zum Beispiel war zum Zeitpunkt des Erstellens dieses Artikels der Mapper noch nicht in der Lage, JAXB Adapter richtig zu interpretieren.

Die Implementierung des Servlet sollte dann wie folgt angepasst werden:


Keine Kommentare

Kontakt

OPEN KNOWLEDGE GmbH

Standort Oldenburg:
Poststraße 1, 26122 Oldenburg

Standort Essen:
II. Hagen 7, 45127 Essen