Der Dokumentation kommt bei Softwareentwicklungsprojekten eine wesentliche Rolle zu. Sie ist speziell im Zuge einer Wartung und Weiterentwicklung sehr wichtig und gewinnt zusätzlich an Bedeutung, wenn Wartungs- und Erweiterungsarbeiten nicht vom Entwicklerteam durchgeführt werden.

Eine besondere Rolle kommt der Dokumentation auch im Hinblick auf die Schnittstellen zwischen den Anwendungen, in der Fachsprache Application Programming Interfaces (API) genannt, zu: APIs verbinden Anwendungen miteinander und mit den jeweiligen Datenquellen und sind in üblichen Anwendungsfällen vielfältig vertreten. Die Beschreibung der Struktur und Funktion einer API ist somit für die Weiterentwicklung einer Software mit zentraler Bedeutung.

Genau dort setzt die Spezifikation Swagger an: Sie setzt auf den Beschreibungsstandard OpenApi, der auch Personen, die nicht unmittelbar am Entwicklungsprozess mitgewirkt haben, die Möglichkeit gibt, APIs zu verstehen oder zu dokumentieren.

 

Swagger ist eine Open Source Programmier-Tool-Sammlung, die zu Dokumentationen von APIs verwendet wird. Als Grundlage dient das Programmierparadigma REST. Das Tool entstand im Jahr 2011 im Zuge eines Entwicklungsprojekts des Wordnik-Mitbegründers, Tony Tam. Es wurde zunächst von mehreren kleineren und unabhängigen Unternehmen und Enwicklerinitiativen unterstützt und lief ab 2014 herstellerneutral mit Open Source Lizenz als Teil der Open-API-Initiative. Am 1. Januar 2016 erfolgte eine Umbenennung der Swagger-Spezifikation in OpenApi Specification und eine Eingliederung in das GitHub Repository. Inoffiziell wird jedoch weiterhin der bekanntere Name Swagger verwendet.

Eine lückenlose, verständliche Dokumentation ist insbesondere für OpenApis unerlässlich. Nur durch eine präzise Schnittstellenbeschreibung wird eine API brauchbar und verwendbar. Swagger gilt aufgrund der Tatsache, dass es so gut wie alle Webservices rund um die Schnittstelle abbilden kann, als die derzeit wohl beste Technologie für die Dokumentation von REST-Apis. Das Tool dokumentiert Änderungen automatisch und sorgt zudem dafür, dass die Dokumentation des REST-Api direkt am Code gespeichert wird. Wenn nicht die Schnittstellenbeschreibung sondern der Programmcode als Ausgangspunkt für eine API-Entwicklung dienen soll, kann Swagger aus diesem unabhängig von der Programmiersprache eine Dokumentation ableiten.

Sowohl die Einsatzmöglichkeiten als auch die Vorteile gegenüber anderen Technologien werden von der Community bei Swagger als so herausragend eingestuft, dass das Tool mit guten Gründen als die derzeit beste Standardanwendung für Schnittstellenbeschreibungen bei RESTful APIs gesehen wird.

Als Open-Source-Tool profitiert Swagger in Sachen Beliebtheit zudem von seiner leichten Verfügbarkeit und hohen Verbreitung. Branchengrößen wie Microsoft, Google und IBM sind im Gremium von Swagger vertreten und sorgen für eine langfristige Sicherung der Position und Wichtigkeit dieser Technologie.

Die Tatsache, dass globaltätige Unternehmen wie Zalando auf die Dienste von Swagger vertrauen, stärkt dessen Einfluss und Ruf zusätzlich. Als einzigen Nachteil könnte man anführen, dass es mitunter etwas Einarbeitung benötigt, um die Dokumentationen zu verstehen. Das Faktum, dass Swagger in der Lage ist, Dokumentationen so zu gestalten und auszulesen, dass sie sowohl für Menschen als auch Maschinen lesbar sind, macht dieses Manko allerdings wieder wett.