Version almost final

lecture: REST APIs dokumentieren mit Swagger

Event_large

Mit Swagger lassen sich Webservice APIs auf einfache Weise dokumentieren und ausprobieren. Im einfachsten Fall wird basierend auf Annotationen im Quellcode eine Spezifikation generiert, die verwendet werden kann, um SDKs zu generieren oder eine HTML-Oberfläche zu erzeugen, mit der im Browser die API live getestet werden kann.

Swagger.io ist ein Framework für die Dokumentation von HTTP Schnittstellen (APIs). Zentraler Bestandteil ist die Spezifikation der Schnittstelle, die die Endpunkte und Datentypen beschreibt und einige Ähnlichkeiten mit JSON Schema aufweist. Im Vortrag wird anhand eines Beispielprojekts gezeigt, wie man basierend auf Java Annotations und einer maven-Task erzeugt so eine Spezifikation erzeugt. Ausgehend von der Spezifikation lassen sich verschiedene Dokumente erzeugen. Der Vortrag zeigt die wesentlichen Anwendungsmöglichkeiten von Swagger auf und geht auch kurz auf mögliche Schwierigkeiten und Defizite ein.

Für Endnutzer interessant ist Swagger UI, eine HTML-Oberfläche, die die Spezifikation einliest und für jeden Endpunkt der API Datenmodelle der Anfrage sowie Antwort dokumentiert und darüber hinaus per Formular die Abfrage der Schnittstelle ermöglicht. Hier bietet sich auch für Entwickler die Möglichkeit eines schnellen Systemtests.

Swagger Codegen lässt sich einsetzen, um SDKs, grafische Visualisierungen oder Mock-Services zu generieren. Im Wesentlichen handelt es sich um ein Scala-basiertes Template Tool, das den in der Spezifikation erzeugten Baum iteriert und je nach Template verschiedene Dokumente erzeugen kann. Im Vortrag wird exemplarisch gezeigt, wie man mit Hilfe von Swagger SDKs für PHP und Java erzeugen kann.