Swagger (Software)

Swagger (von englisch Prahlerei) ist eine Sammlung von Open-Source-Werkzeugen, um HTTP-Webservices (auch HTTP API oder REST-like API) zu entwerfen, zu erstellen, zu dokumentieren und zu nutzen.^[1] Swagger benutzt dazu den Beschreibungsstandard OpenAPI.

Swagger wird von vielen weiteren Tools erkannt und unterstützt. Während die meisten Benutzer bei „Swagger“ an das Swagger-UI-Tool denken, bietet das Swagger-Toolset Unterstützung für automatisierte Dokumentation, Code-Generierung und Testfallgenerierung. Swagger gehört neben RAML und API Blueprint zu den häufig verwendeten API-Beschreibungssprachen.^[2][3]

Geschichte

Das Swagger-API-Projekt wurde 2011 von Tony Tam, dem technischen Mitbegründer der Wörterbuchseite Wordnik, ins Leben gerufen. Während der Entwicklung von Wordniks Produkten wurde die Notwendigkeit der Automatisierung der API-Dokumentation und der Generierung von Client-SDKs zu einer Hauptquelle der Frustration. Tam entwarf eine einfache JSON-Darstellung der API, die auf der Flexibilität der REST-Architektur aufbaut und viele Funktionen der für das SOAP-Protokoll entwickelten Werkzeuge nutzt. Die Benutzeroberfläche wurde von Ayush Gupta konzipiert, der vorschlug, dass eine interaktive Benutzeroberfläche Endbenutzern, die gegen die API „ausprobieren“ und entwickeln wollten, zugutekommen würde. Ramesh Pidikiti leitete die Implementierung des ersten Codegenerators und Designer/Entwickler Zeke Sikilianos prägte den Namen Swagger. Das Swagger-API-Projekt wurde im September 2011 zum Open-Source-Projekt gemacht. Bald nach der Veröffentlichung wurde dem Projekt eine Reihe neuer Komponenten hinzugefügt, darunter ein eigenständiger Validator, Unterstützung für Node.js und Ruby on Rails.

In den ersten Jahren wurde Swagger von kleinen Unternehmen und unabhängigen Entwicklern beeinflusst. RESTful APIs hatten normalerweise keinen maschinenlesbaren Beschreibungsmechanismus, und Swagger bot einen einfachen und auffindbaren Weg, dies zu tun. Tam wurde zu einem Treffen mit einigen Vordenkern der API-Technologie eingeladen, darunter John Musser (Programmable Web), Marsh Gardiner (Apigee, jetzt ein Google-Produkt), Marco Palladino (Mashape) und Kin Lane (API Evangelist), um eine Standardisierungsbemühung rund um API-Beschreibungen zu diskutieren. Das Treffen brachte zwar keinen konkreten Plan, aber Swagger als wichtige Neuerung im API-Bereich auf die Landkarte.

Unterstützt durch die Verwendung der Apache 2.0 Open-Source-Lizenz, begann eine Reihe von Produkten und Online-Diensten, Swagger in ihr Angebot aufzunehmen, was sich nach der Übernahme durch Apigee, Intuit, Microsoft, IBM und andere, die das Swagger-Projekt öffentlich zu unterstützen begannen, schnell beschleunigte.

Kurz nach der Gründung von Swagger wurden alternative Strukturen zur Beschreibung von RESTful APIs eingeführt, wobei die beliebtesten im April 2013 API Blueprint und im September 2013 RAML waren. Während diese Konkurrenzprodukte finanziell stärker unterstützt wurden als Swagger, konzentrierten sie sich zunächst auf verschiedene Anwendungsfälle von Swagger, und ab Mitte 2014 wuchs das Interesse an Swagger schneller als die Kombination der beiden anderen.

Im November 2015 gab SmartBear Software (das Unternehmen, das Swagger pflegt) bekannt, dass es beim Aufbau einer neuen Organisation unter der Schirmherrschaft der Linux Foundation, der Open-API-Initiative, helfe. Eine Vielzahl von Unternehmen, darunter Google, IBM und Microsoft, waren Gründungsmitglieder.

Am 1. Januar 2016 wurde die Swagger-Spezifikation in OpenAPI-Spezifikation umbenannt und in ein neues Repository in GitHub verschoben. Obwohl die Spezifikation selbst nicht geändert wurde, bedeutete diese Umbenennung die Trennung zwischen dem API-Beschreibungsformat und dem Open-Source-Tooling.

Seit Juli 2017 werden Swagger-Tools mehr als 100.000 Mal pro Tag heruntergeladen, je nach den Hosting-Repositories Sonatype und NPM.

Verwendung

Swagger arbeitet mit vielen der gängigen Programmiersprachen wie Java, Scala, Clojure, Groovy, JavaScript und C#.

Das Swagger-Open-Source-Tooling kann in verschiedene Anwendungsfälle aufgeteilt werden:

Entwicklung von APIs

Bei der Erstellung von APIs kann Swagger Tooling verwendet werden, um automatisch ein Open-API-Dokument basierend auf dem Code selbst zu erzeugen.^[4] Dies wird informell als Code-First- oder Bottom-up-API-Entwicklung bezeichnet. Während der Softwarecode selbst das Open-API-Dokument genau darstellen kann, halten viele API-Entwickler dies für eine veraltete Technik, da er die API-Beschreibung in den Quellcode eines Projekts einbettet und es für Nicht-Entwickler typischerweise schwieriger ist, dazu beizutragen. Swagger unterstützt auch JAX-RS.^[5]

Alternativ können Entwickler mit Swagger Codegen den Quellcode vom Open-API-Dokument entkoppeln und Client- und Servercode direkt aus dem Entwurf generieren. Obwohl dies als kompliziert angesehen wird, wurde es von vielen Branchenexperten als ein modernerer API-Workflow angesehen und erlaubt mehr Freiheit bei der Gestaltung der API, indem der Coding-Aspekt verschoben wird.

Interaktion mit APIs

Mit dem swagger-codegen-Projekt generieren Endanwender Client-SDKs direkt aus dem Open-API-Dokument, wodurch der Bedarf an von Menschen generiertem Client-Code reduziert wird. Seit August 2017 unterstützt das Projekt swagger-codegen mehr als 50 verschiedene Sprachen und Formate für die Erstellung des Client-SDKs.

Dokumentation von APIs

Wenn durch ein Open-API-Dokument beschrieben, kann Swagger Open-Source-Tooling verwendet werden, um direkt mit der API über die Swagger-Benutzeroberfläche zu interagieren. Dieses Projekt ermöglicht die direkte Anbindung von Live-APIs über eine interaktive, HTML-basierte Benutzeroberfläche.

Literatur

• Jobinesh Purushothaman: RESTful Java Web Services, Packt Publishing, ISBN 978-1784399092, Seite 242 ff eingeschränkte Vorschau in der Google-Buchsuche

Weblinks

• editor.swagger.io – Editor und Testumgebung einer json-Datei im Format OpenAPI/Swagger (startet mit einer Demo-Datei)
• swagger.io – Offizielle Website (nur in englisch)
• inspector.swagger.io – Offizieller Swagger Inspector (Onlineversion)
• Dennis Kieselhorst: Swagger: Mehr als nur Schnittstellenbeschreibung Die OpenAPI Specification alias Swagger entwickler.de

Einzelnachweise

1. ↑ Dinesh Rajput: Mastering Spring Boot 2.0 eingeschränkte Vorschau in der Google-Buchsuche
2. ↑ REST-APIs mit Node.js und Swagger Heise
3. ↑ RESTful APIs dokumentieren – so geht’s! jaxenter.de
4. ↑ Marko Lukša: Kubernetes in Action eingeschränkte Vorschau in der Google-Buchsuche
5. ↑ Bogunuva Mohanram Balachandar: RESTful Java Web Services eingeschränkte Vorschau in der Google-Buchsuche