Swagger-API-Dokumentation für Anfänger – Teil 1: Einführung in die API-Dokumentation mit Swagger

Was ist Swagger?

Das Ziel von Swagger™ ist es, einen standardisierten, sprachunabhängigen Zugang zu REST-APIs zu definieren. Damit können sowohl Menschen als auch Computer die Funktionen eines Dienstes verstehen und nutzen – ohne Zugriff auf den Quellcode, die Dokumentation oder durch Netzwerkverkehrsanalyse. Wenn eine API korrekt mit Swagger beschrieben ist, kann ein Nutzer mit minimalem Aufwand verstehen und mit dem Remote-Dienst interagieren. Ähnlich wie Schnittstellen in der niedrigstufigen Programmierung die Arbeit erleichtern, beseitigt Swagger die Unsicherheit beim Aufruf eines Dienstes.

Technisch gesehen ist Swagger eine formale Spezifikation, umgeben von einem großen Ökosystem an Tools. Dazu gehören Frontend-Oberflächen, Low-Level-Bibliotheken und kommerzielle Lösungen für das API-Management.

Wie fange ich an?

Falls du API-Anbieter bist und Swagger nutzen möchtest, um deine APIs zu beschreiben, gibt es mehrere Ansätze:

Ein *top-down*-Ansatz, bei dem du den Swagger Editor verwendest, um deine Swagger-Definition zu erstellen, und dann die integrierten Swagger Codegen-Tools nutzt, um die Server-Implementierung zu generieren.
Falls