Swagger: Wenn die Schnittstellen-Dokumentation sich selber schreibt

„Der Quelltext ist die Dokumentation.“ Diesen Satz hört man oft, wenn es um die Dokumentation in Entwicklungsprojekten geht. Gerade wenn Zeit und Budget knapp sind wird gerne an der Dokumentation des Softwaresystems gespart. Diese ist zwar zeitaufwendig, jedoch hilfreich für die Wartung und Weiterentwicklung des Systems. Das ist besonders dann der Fall, wenn die Software nicht von dem Team gewartet bzw. erweitert wird, das sie entwickelt hat. Häufig wächst die Dokumentation jedoch nicht gleichmäßig mit dem entwickelten System und bleibt manchmal aufgrund von Termindruck sogar ganz auf der Strecke.^[1]

Eine vielleicht noch größere Bedeutung als die Dokumentation des Codes für Wartungs- und Erweiterungszwecke hat die Dokumentation der Schnittstellen, über die man auf das Softwaresystem zugreifen kann. Um eine solche API zu verwenden, ist es notwendig, die Struktur und die angebotenen Funktionen zu kennen. Die Voraussetzung dafür ist eine hohe Qualität der API-Dokumentation.

Ein gängiges Programmierparadigma für die Entwicklung dieser APIs ist Representational State Transfer (REST). Viele Webseiten verwenden RESTful APIs, dazu zählen Amazon, Google, LinkedIn und Twitter.^[2] Für die Beschreibung dieser REST-APIs gibt es keinen Standard. Allerdings gibt es unterschiedliche Best Practices, die im Laufe der Zeit entstanden sind.

Swagger

Ein Format zur Beschreibung einer REST-API ist Swagger, das von Reverb entwickelt wurde und als Open Source zur Verfügung steht. Laut Google Trends handelt es sich dabei um eine der populärsten Technologien im Bereich der API Dokumentation.^[3] Swagger basiert auf einer JSON-Datei und auf Swagger UI, eine Benutzeroberfläche auf Basis von HTML und JavaScript. Neben der Dokumentation der Schnittstelle kann Swagger auch für das Ausführen von Ad-hoc-Tests verwendet werden.^[4]

Eine der zentralen Stärken von Swagger ist das umfassende Ökosystem auf GitHub. Es gibt Codegeneratoren für unterschiedliche Programmiersprachen, für Java werden beispielsweise Annotations angeboten.^[5]

Damit sich die Schnittstellendokumentation möglichst nahe an der Implementierung orientiert, lassen sich mit Swagger die nötigen Informationen direkt am Java-Code platzieren.

Die Integration mit Spring Boot ist schnell erledigt, dazu kann die Swagger 2 Implementierung Springfox verwendet werden. Zunächst muss die Abhängigkeit zum Maven Projekt in der pom.xml Datei hinzugefügt und mit der Annotation @EnableSwagger2 aktiviert werden. Zusätzlich wird eine weitere Dependency benötigt, um Swagger UI verwenden zu
können.^[6]

Ab diesem Zeitpunkt schreibt sich die Schnittstellen-Dokumentation fast von selbst. Bei jeder Schnittstelle können über die entsprechenden Swagger Annotations alle benötigten Informationen hinterlegt und die Schnittstelle so dokumentiert werden.

@RestController
@Api
@RequestMapping(path = "/users")
public class UserResource{

@ApiOperation(value = "Creates a new user account")
 @PostMapping("/users")

public void addUsers()
 {…}


@ApiOperation(value = "Gets al list of users (filtered and sorted)")
 @GetMapping("/{userids} ")

public void getUsers(@PathVariable List<Long> userids)
 {…}


@ApiOperation(value = "Deletes an existing user account")
 @DeleteMapping("/{userids}")

public void deleteUsers(@PathVariable List<Long> userids)
 {…}

}

Auch für OSGi ist eine einfache Swagger Integration verfügbar. Dadurch kann Swagger mithilfe des OSGi Configuration Admins konfiguriert werden. Der OSGi-JAX-RS Connector ermöglicht eine Swagger Integration in ein separates Bundle  ‚com.eclipsesource.jaxrsprovider.swagger‘, das in derselben OSGi Instanz wie die JAX-RS Ressourcen gestartet werden
muss.^[7]

Die Dokumentation kann anschließend wieder über Annotations direkt an den Java Klassen hinterlegt werden.

@Path("/tickets")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Api(value = "/tickets")
public interface UserResource
{
@GET
 @ApiOperation(value = "Gets al list of tickets.")
 @ApiResponses(value = {@ApiResponse(code = HttpStatus.SC_UNAUTHORIZED, message =" not valid"),
 @ApiResponse(code = HttpStatus.SC_INTERNAL_SERVER_ERROR, message = "internal problem“})
 Ticket getTickets();
}

Dabei können zusätzliche Informationen angegeben werden, wie der zurückgegebene oder benötigte Datentyp oder mögliche Fehlerfälle mit dem jeweiligen HTTP Status Code und ggf. detaillierten Fehlerbeschreibungen.

Im .NET Umfeld gibt es ebenfalls die Möglichkeit einer Swagger Integration. Hier existiert z.B. das Open Source Projekt Swashbuckle, mit dem eine Swagger-Dokumentation für ASP.NET-Web-API-basierte Projekte generiert werden kann. Swashbuckle kann über NuGet in das Web-API-Projekt geladen werden.^[8]

Neben Java und .NET bietet das umfangreiche Ökosystem auf GitHub auch Swagger Implementierungen für andere Programmiersprachen.

Swagger-Spezifikation

Eine Swagger-Spezifikation benötigt immer Metainformationen wie einen Titel und eine Version. Nicht zwingend notwendig sind Hostname und Basispfad. Außerdem können globale Parameter, Antwortnachrichten und Datentypen spezifiziert werden. Der API Endpunkt /users/{userid} ermöglicht es beispielsweise, die Ressource User über eine ID zu finden. In der Antwortnachricht mit dem Statuscode 200 wird das User-Datenmodell zurückgeliefert.

Beispielhaft sei die API von der Datentransferlösung calvaDrive genannt, die ebenfalls mit Swagger dokumentiert wurde.

In nachfolgender Abbildung ist die Swagger Dokumentation der GET Methode der REST Ressource ‚settings‘ abgebildet. Diese beinhaltet u.a. eine allgemeine Beschreibung der Methode sowie mögliche zurückgegebene HTTP Statuscodes mit jeweiliger Beschreibung. Zudem wird der Rückgabe-Datentyp abgebildet, in diesem Fall JSON, sowie die Struktur des Settings-Objekts, das von der REST Ressource zurückgegeben wird.

Mit der steigenden Verwendung von Microservices, gewinnt auch die Dokumentation interner APIs immer mehr an Bedeutung. Bei einer Microservice-Architektur haben die unterschiedlichen Komponenten eine funktionale Unabhängigkeit und kommunizieren über Schnittstellen. Das steigert die Modularität eines Softwaresystems, wodurch die Gesamtkomplexität verringert werden kann.^[9]

Microservices haben den Vorteil, dass man sie unabhängig voneinander entwickeln und deployen kann. Es muss jedoch Schnittstellen geben, über die sie Daten austauschen können. Wenn es z.B. in einem Softwaresystem einen Microservice für die Suche und einen für die Bestellung gibt, müssen diese Komponenten über eine Schnittstelle Informationen weitergeben können. Werden zwei eng gekoppelte Komponenten von zwei verschiedenen Teams entwickelt, sind Absprachen über die APIs notwendig, was die Geschwindigkeit der Entwicklung reduziert.^[10] Somit bietet eine hohe Qualität der Schnittstellendokumentation gerade im Microservice-Umfeld große Vorteile.

Sowohl für öffentliche als auch für interne APIs ist eine verständliche Dokumentation entscheidend, damit sie von Entwicklern eingesetzt werden können.  Gerade bei verteilten Teams ist die Dokumentation von internen Schnittstellen sehr wichtig. Bei öffentlichen APIs ist die Dokumentation entscheidend für ihre Verbreitung und damit für die Wettbewerbsfähigkeit.

Bei Swagger handelt es sich um das im Moment am weitesten verbreitete Spezifikationsformat für HTTP-basierte APIs.^[11] Es ist eine gute Möglichkeit, um REST Schnittstellen zu dokumentieren, lediglich HATEOAS kann mit diesem Framework derzeit noch nicht abgebildet werden.^[12] 

Mithilfe von Swagger kann die Dokumentation der REST Schnittstellen direkt am Code hinterlegt und weitgehend automatisiert erzeugt werden. Das ist ein entscheidender Vorteil, denn Schnittstellen-Dokumentation ist zwar wichtig, benötigt jedoch auch immer Zeit und damit Projektbudget. Außerdem kann dadurch sichergestellt werden, dass die Dokumentation gleichmäßig mit dem entwickelten System wächst und bei Änderungen angepasst wird.

Quellen:

^[1] http://www.pc-magazin.de/business-it/webprojekte-sinnvoll-dokumentieren-2108112.html
^[2] http://www.searchenterprisesoftware.de/definition/RESTful-API
^[3] https://jaxenter.de/entwicklung-und-dokumentation-von-rest-apis-20099
^[4] http://t3n.de/news/api-browser-swagger-ui-624096/
^[5] http://t3n.de/news/api-browser-swagger-ui-624096/
^[6] http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
^[7] https://github.com/hstaudacher/osgi-jax-rs-connector/wiki/Swagger-Integration
^[8] https://entwickler.de/online/web-apis-mit-swagger-dokumentieren-160148.html
^[9] https://jaxenter.de/microservices-agilitaet-mit-architektur-skalieren-19499
^[10] https://jaxenter.de/microservices-agilitaet-mit-architektur-skalieren-19499
^[11] https://jaxenter.de/restful-apis-dokumentieren-52052
^[12] https://jaxenter.de/restful-apis-dokumentieren-52052