REST Service Dokumentation mit Swagger

REST Services erfreuen sich seit einigen Jahren immer größerer Beliebtheit. Während SOAP Services als unflexibel und unnötig kompliziert gelten, sind REST Services schlank und bestehende Schnittstellen sind nicht so "empflindlich" gegenüber Änderungen. Z. B. lassen sich Services und Query-Parameter hinzufügen, ohne dass der Schnittstellenvertrag gebrochen wird.

Einen großen Nachteil haben REST Services jedoch gegenüber SOAP mit WSDL: die WSDL definiert die Schnittstelle und ermöglicht es einem Client so, das Interface sehr einfach mit wenigen Zusatzinformationen anzusprechen. Es gibt Tools die anhand einer WSDL Stubs (Client Klassen) erstellen können, sodass schnell klar wird, wie die Schnittstelle zu bedienen ist. Zwar gibt es auch bei REST vergleichbare Ansätze (siehe z. B. WADL), diese konnten sich jedoch in der Praxis nicht wirklich durchsetzen.

Umso wichtiger ist es daher, die REST Services umfassend zu dokumentieren und die Doku auch aktuell zu halten. Genau hier setzt Swagger an. Mit Swagger lassen sich die Services sehr komfortabel über Annotations beschreiben. Dadurch dass zur Erstellung der Doku Informationen direkt aus dem Quelltext zu Rate gezogen werden, ist stets Aktualität gewährleistet. Des weiteren bietet Swagger eine HTML Oberfläche, um die Doku zu präsentieren und die Services direkt auszuprobieren.

Im Folgenden werden die wenigen notwendigen Schritte beschrieben, um Swagger im eigenen Projekt nutzen zu können. (basierend auf einem JAX-RS und Maven Projekt)

Zunächst muss die Swagger-Lib als Dependency aufgenommen werden: 

<dependency>

    <groupId>io.swagger</groupId>

    <artifactId>swagger-jaxrs

    <version>1.5.9</version>

    <scope>compile</scope>

</dependency>

Anschließend muss die Rest- "Application" Klasse um folgenden Konstruktor ergänzt werden (falls JAX-RS verwendet wird): 

//Swagger initialization
public Application() {
    BeanConfig beanConfig = new BeanConfig();
    beanConfig.setVersion("1.0");
    beanConfig.setTitle("Meine REST services");
    beanConfig.setBasePath("/anwendung/service");
    //Hier befinden sich die Rest-Services
    beanConfig.setResourcePackage
    ("de.stahl.restservice");
    beanConfig.setScan(true);
}

Swagger UI wird benötigt, um die Dokumentation als Web-App bereitzustellen. Dazu muss die Web-Anwendung heruntergeladen werden (http://swagger.io/swagger-ui/) und der Inhalt des "dist" Ordners (swagger-ui/dist) in den Ordner "src/main/webapp" bereitgestellt werden. 

Damit die Dokumentation schließlich auch erstellt wird, müssen die Services noch mit den passenden Annotations versehen werden, die eine Beschreibung der Funktionalität beinhalten, zum Beispiel:

•  Auf Klassenebene: 

@Api(value="Mein REST Service")

•  Auf Methodenebene: 

@ApiOperation(value = "Beschreibung der API Operation") @ApiParam(value = "ein wichtiger Parameter", required = true) 

Diese Schritt reichen aus, um die Dokumentation zu erstellen. Detailliertere Informationen zu den verfügbaren Annotations gibt es hier: https://github.com/swagger-api/swagger-core/wiki/Annotations

Offline-Nutzung

Es könnte notwendig sein, eine Schnittstellendokumentation zu erstellen, obwohl der Quelltext noch gar nicht fertiggestellt wurde, z.B. wenn ein externe Komponente frühzeitig Informationen über eine sich in der Entwicklung befindliche Schnittstelle benötigt. Auch dies ist mit Swagger möglich.

Dazu wird zunächst die Swagger-Definition (JSON-File) erstellt. Dies kann mit Hilfe des Swagger Editors geschehen: http://editor.swagger.io/#/

Dann wird das resultierende JSON in die index.html der Swagger-Web-Anwendung eingefügt und das SwaggerUi-Objekt initialisiert: 

var spec = {"json":"test"};

window.swaggerUi = new SwaggerUi({

   url:url,

   spec: spec,

   ...

Da die Swagger Web-App ausschließlich auf HTML und Javascript basiert, kann diese anschließend, z.B. als Zip-Archiv and die potenziellen Clients verteilt werden.

JRebel Support

Als JRebel Fan möchte ich noch erwähnen, dass Swagger nun auch von JRebel wunderbar unterstützt wird. (siehe https://zeroturnaround.com/forums/topic/support-for-swagger/) Dies ist sehr hilfreich, um die Änderungen an der Dokumentation und den Annotations direkt in der Oberfläche nachvollziehen zu können.