Swagger (OpenAPI Specification): Erklärung, Einsatz & Vorteile


Das Kernelement von Swagger ist je nach Einsatzgebiet eine JSON– oder eine YAML-Datei. Die Benutzeroberfläche, mit der man die Dokumentationen ganz leicht erstellen kann, basiert auf HTML und JavaScript. Grundsätzlich hat Swagger ein sprachneutrales und maschinenlesbares Format. Über das User-Interface lässt sich nicht nur die Dokumentation verwalten, sondern mit ihm kann Swagger zum Beispiel auch Ad-hoc-Tests durchführen.

Ein Vorteil von Swagger wird auch im umfangreichen Erweiterungsmodus sichtbar, der durch eine Kernbibliothek, dem Swagger-Core, unterstützt wird. Die Benutzeroberfläche wird Swagger UI genannt, der Codegenerator Swagger Codegen, darüber hinaus gibt es einen Swagger Editor.

Aber die größte Stärke zieht Swagger, wie viele Open-Source-Angebote, aus dem umfassenden Ökosystem von GitHub. Hier finden Entwickler Codegeneratoren für nahezu alle Programmiersprachen. Swagger dokumentiert jede Schnittstelle mit allen Informationen.

Die Dokumentationsdatei beginnt mit der Angabe der verwendeten Spezifikationsversion, dann folgen die generellen Informationen zum API, klar sortiert unter der Kategorie info. Swagger trennt auch Host, Pfad und URL-Schema und gibt sie einzeln an. Erst danach erfolgt der Mediatype für die gesamte API. Diese Aufbereitung ist wie ein komplexes Karteikartensystem.

Erst nach dieser Kategorisierung werden die Inhalte dargestellt: Pfade, Operatoren und Parameter werden mitsamt der zugehörigen Beschreibung aufbereitet. Datentypen werden extra in einem eigenen Abschnitt verwaltet. Durch das Swagger UI lässt sich das Ganze nicht nur in Textform darstellen, sondern auch grafisch visualisieren. Das ist vor allem von Vorteil, wenn direkte Testanfragen aus dem Browser gesendet werden sollen. Diese Mischung aus perfekter Dokumentation und der gleichzeitigen Möglichkeit, direkte API-Anfragen auszulösen, macht Swagger so wertvoll.



Source link

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.