Automatische API-Dokumentation Swagger und OpenAPI im Einsatz

Swagger feiert dieses Jahr den zehnten Geburtstag und findet sich bald täglich in irgendeiner neuen Anwendung – oder auch in ältere. Was kann Swagger und warum ist es so beliebt?

Swagger ist im Grunde dreierlei: Eine Spezifikation, eine Sammlung von Open-Source-Werkzeugen sowie ein kommerzielles Angebot von Smartbear. Es dient der Umsetzung und Dokumentation von REST-APIs und verfolgt dabei konsequent die Idee, dass Nutzer die Funktionen der API direkt ausprobieren können. Damit vereinfacht Swagger den Einstieg in eigenes Scripting oder Tool-Entwicklung.

Ein kurzer Abriss: Swagger startete 2011 und wurde auch im selben Jahr noch als Open-Source-Projekt veröffentlicht. Die Hauptanliegen waren eine automatische Dokumentation der API – ansonsten eine zeitintensive, lästige Arbeit für die Entwickler – und eine interaktive Nutzeroberfläche. Im Jahr 2015 hatte Swagger die Konkurrenz ein- beziehungsweise überholt und wurde 2016 zur OpenAPI Specification umbenannt.

Im Zuge dessen wurde das Projekt auf Github verschoben, unterstützt vom Ur-Entwickler Smartbear sowie unter anderem Google, IBM und Microsoft. Die Schirmherrschaft der Gründung der OpenAPI Initiative lag wie so oft bei der Linux Foundation. Und so laufen heute die Spezifikationen unter OpenAPI, die freien Tools werden unter dem Namen Swagger bei Github gepflegt und die kommerziellen Angebote selben Namens nach wie vor direkt auf der Smartbear-Webseite Swagger.io.

Vielleicht haben Sie von Swagger noch nie etwas gehört oder gesehen – darum zäumen wir das Pferd einmal von hinten auf und zeigen zunächst mal ein Endergebnis. Im Folgenden also das Demoprojekt von Smartbear, der sogenannte Pet Store.

Wir sehen hier den Swagger Editor, den Sie auch direkt online nutzen können, samt der Beispiel-OpenAPI-Definition des Swagger Petstores. Daneben finden auch gleich die zugehörige grafische Nutzeroberfläche Swagger UI.

Wie genau der OpenAPI-Code aufgebaut ist, können Sie freilich der sehr guten OpenAPI-Spezifikation auf GitHub entnehmen, aber Sie sehen schon im Screenshot: Der Aufbau ist sehr strukturiert, dabei aber wesentlich besser lesbar als etwa XML. Swagger UI auf der rechten Seite direkt und live die möglichen API-Anfragen – und genau an der Stelle können Sie (potenziellen) Kunden und Interessenten sehr schnell Mehrwert bieten.

Dieses Bild zeigt nun den API-Part, der für das Auflisten der im Store verfügbaren Haustiere nach Status („Finds Pets by status“) ermöglicht – links als Code, rechts als interaktive Abfrage. Nicht mehr im Bild ist das Ergebnis der Anfrage, sprich eine XML-Ausgabe der verfügbaren Artikel; alternativ ließe sich hier auch eine JSON-Ausgabe erstellen. Enorm hilfreich sind bei Swagger UI des Petstores vor allem auch die Ausgaben für Request-URL und curl-Kommando – es sind genau diese Syntax- und Praxishilfen, die interessierten Client-Entwicklern oder normalen API-Nutzern den Einstieg enorm vereinfachen.

Damit haben Sie nun Swagger Editor und Swagger UI gesehen, es fehlt noch das dritte Open-Source-Tool im Bunde, Swagger Codegen – und das verbirgt sich schlicht in den beiden Menüs „Generate Server“ und „Generate Client“ im Editor.

Mittels Codegen lassen sich Server-Vorlagen in über 20 und Client-SDKs in über 40 Sprachen generieren. Wenn Sie dies mit dem Petstore ausprobieren, bekommen Sie Pakete inklusive Installations- und Konfigurationsanweisungen, Hilfen für Docker, Git-Repos oder beispielsweise einer Konfigurationsdatei zum Aktivieren von automatischer Vervollständigung für den Bash-Client.

Was noch fehlt ist die eigentliche, natürlich auch automatisch erstellte Dokumentation – wobei Swagger UI im Grunde schon etliche Informationen mit sich bringt. Ein Beispiel für die Petstore-Dokumentation mit der Auszeichnungssprache ReDoc findet sich bei GitHub.

Schon in dieser minimalen Variante bekommen Sie eine aufgeräumte Dokumentation mit Beispielen für Payloads, HTTP-Antworten, Modellen und auch konkrete Beispielaufrufe für Beispielserver. Das geht aber noch ausführlicher.

Real-World-Beispiel

Im Falle des Petstores darf man getrost davon ausgehen, dass die Direktive „Design first“ hieß, aber freilich lässt sich Swagger auch auf bestehenden Code anwenden. Das Vorgehen dabei ist im Grunde ziemlich straight-forward: Es werden Annotationen im Quellcode hinterlegt, aus denen wiederum die OpenAPI-Beschreibung erstellt wird. So konnte man es zum Beispiel bei der Monitoring-Lösung Checkmk sehen.

Hier also nochmals eine ReDoc-Dokumentation aus der Praxis. Rechts im Bereich „Request samples“ spielt sich die eigentliche Magie ab: Sie bekommen hier ganz konkrete Python- und Bash-Skripte für Standards wie die Bibliothek urllib oder curl, aber auch für den vielversprechenden „API-Client“ httpie, der für diese Zwecke komfortabler als curl ist und den wir Ihnen auch noch ganz explizit vorstellen. Natürlich können Sie für Ihre Projekte an dieser Stelle auch Code für C#, PHP oder sonstige Sprachen hinterlegen.

Neben ReDoc und den freien Smartbear-Swagger-Werkzeugen gibt es noch Dutzende von Frameworks, Sprachintegration und sonstigen Open-Source-Tools für Swagger/OpenAPI – bis hin zu Plug-and-Play-CLIs. Eine Auflistung der Open-Source-Integrationen mit Swagger finden sich auf der Projekt-Website.

Hinzu gesellen sich wie anfangs erwähnt die kommerziellen Angebote von Smartbear, nämlich SwaggerHub und Swagger Inspector. SwaggerHub liefert dabei die komplett gehostete Variante inklusive Collaboration-Tools, erweitertem Editor, Third-Party-Integrationen, automatischen Mockups und in der Enterprise-Version zudem API-Standardisierung, On-Premises-Installationen und dergleichen.

Swagger hat sich in den letzten Jahren mehr und mehr als Standard etabliert, die Bedeutung von APIs ist exponentiell gestiegen – immer häufiger arbeiten Unternehmen nach dem Motto „Design/API first“, wie es zum Beispiel Zalando ausführlich dokumentiert. Und der httpie-Slogan „HTTP client for the API era“ kommt auch nicht von ungefähr. Swagger bietet dabei sowohl für den API-Entwickler/-Anbieter als auch für die API-Nutzer und Drittentwickler einige interessante Features und vor allem Arbeitsersparnis.

Was nun wäre ein Artikel über Entwicklungswerkzeuge ohne Atlassian – mindestens eine Seltenheit: Auf Bitbucket finden Sie auch von Atlassian einen OpenAPI-/Swagger-Beitrag in Form eines Validators als Java-Bibliothek. Falls also etwaige API-Arbeiten anstehen, wäre OpenAPI sicherlich ein Jira-Ticket wert.

(ID:47375265)