Swagger ist eine Familie von Werkzeugen für Schnittstellen, die nach dem Standard OpenAPI beschrieben sind. Ursprünglich war Swagger auch der Name dieses Standards selbst, deshalb werden beide Begriffe bis heute oft gleichbedeutend verwendet.
- Swagger
Eine Sammlung von Werkzeugen des Unternehmens SmartBear, mit denen sich OpenAPI-Beschreibungen schreiben, als Dokumentation anzeigen und in Code umsetzen lassen.
Beispiel: „Unter /docs zeigt die Schnittstelle ihre Endpunkte mit Swagger UI an, jeder lässt sich dort direkt ausprobieren.“Abgrenzung zu OpenAPI: OpenAPI ist der Standard, also das Format der Beschreibung. Swagger bezeichnet heute die Werkzeuge, die damit arbeiten. Eine Swagger-Datei im älteren Sprachgebrauch ist eine OpenAPI-Datei der Version 2.0.
Woher Swagger kommt
Entwickelt hat es Tony Tam um 2010 beim Wörterbuchdienst Wordnik, um die eigene Schnittstelle zu beschreiben. 2015 übernahm SmartBear das Projekt und brachte die Spezifikation in die neu gegründete OpenAPI Initiative ein, wo sie 2016 in OpenAPI umbenannt wurde.
Der Name Swagger blieb bei den Werkzeugen. Die Version 2.0 der Spezifikation heißt deshalb bis heute oft Swagger 2.0, ab Version 3.0 spricht man von OpenAPI.
Die wichtigsten Swagger-Werkzeuge
Swagger UI macht aus einer OpenAPI-Datei eine Seite im Browser, auf der jeder Endpunkt mit Beispielen beschrieben ist und sich mit eigenen Werten aufrufen lässt. Swagger Editor ist ein Editor mit Vorschau und Prüfung für solche Dateien, Swagger Codegen erzeugt daraus Clients und Gerüste für den Server.
Alle drei sind quelloffen. Dazu kommt ein kostenpflichtiges Angebot von SmartBear für Teams, die Schnittstellen gemeinsam entwerfen und verwalten.
Swagger UI und Sicherheit
Eine öffentlich erreichbare Swagger-Seite zeigt jedem, welche Endpunkte es gibt und was sie erwarten. Für Schnittstellen, die nur intern gedacht sind, gehört sie deshalb hinter eine Anmeldung oder wird im Echtbetrieb abgeschaltet.
Ein echtes Risiko entsteht erst, wenn die Schnittstelle selbst schwach geschützt ist. Anmeldung und Rechte müssen deshalb bei jedem Endpunkt geprüft werden, ob die Dokumentation öffentlich ist oder nicht.