API Dokumentation mit Open API

1. Warum überhaupt eine API dokumentieren?

Auch wenn die Frage für viele von euch vielleicht überflüssig erscheint, möchte ich kurz auf die Motivation zur Dokumentation von APIs eingehen. Einer der Hauptgründe für die Dokumentation von Software ist wohl die Projektübergabe. Oft musst du als Developer:in an einem Code weiterarbeiten, der von jemand anderem entwickelt wurde. Es ist denke ich klar, dass dir das umso leichter fallen wird, umso besser der bestehende Code dokumentiert ist. 

Bei APIs gibt es aber noch ein paar weitere Gründe, warum eine Dokumentation wichtig ist. Eine API dient ja grundsätzlich immer dazu, verschiedene voneinander entkoppelte Softwarekomponenten miteinander zu verbinden. Da aber bei größeren Projekten meist nicht nur eine Person beteiligt ist, sondern oft das Team in Backend und Frontend aufgeteilt wird, ist die Dokumentation auch hier extrem wichtig, damit alle Entwickler:innen wissen, wie die Schnittstelle funktioniert, bzw. funktionieren sollte.

Also auch für die Person, welche die API dann schlussendlich entwickelt, ist die Dokumentation von großer Bedeutung, da damit eine “Source of Truth” geschaffen wird, die schlussendlich definiert, wie die Schnittstelle technisch zu funktionieren hat. Man spricht daher auch gern von einer API Spezifizierung. Ein letzter Punkt, den ich noch erwähnen möchte, ist Testing. Egal ob automatisiert getestet wird oder manuell, eine gute Dokumentation ist ein solide Grundlage um Testfälle zu erstellen. 

2. Wie dokumentiert man nun eine API?

Nachdem wir das “Was” gekonnt übersprungen haben und auf das “Warum” bereits eingegangen sind, wollen wir uns endlich dem “Wie” widmen. Auf den ersten Blick scheint die Frage recht trivial. Man schreibt einfach irgendwo nieder, wie das Ding funktioniert, oder?

Klar kann man das machen, auch wir haben in der Vergangenheit einfach Tabellen angelegt, in denen jeder Endpoint einzeln aufgelistet wird und dafür Dinge wie HTTP-Methode, Request und Response niedergeschrieben werden. Der Ansatz ist nicht unbedingt falsch, es gibt quasi keine Einarbeitungszeit für Developer:innen und die Sache ist auch vergleichsweise mit relativ wenig Aufwand erledigt. 

Dennoch tun sich gerade bei größeren Projekten auch einige Probleme mit dieser Methode auf. Das liegt vor allem daran, dass in der Praxis selten alle Endpoints komplett unterschiedlich sind, sondern sich immer gewisse Muster wiederfinden lassen. Ändert man nun etwas in der Codebase, so kann es schnell mühsam werden.

Nur ein Feld hinzugefügt und schon muss man die Dokumentation von jedem Endpoint einzeln anpassen. Genau hier kann ein standardisiertes Format wie OpenApi Abhilfe schaffen, indem es erlaubt, Schemata und Komponenten zu definieren, die dann von mehreren Endpoints verwendet werden können. Auch eine Referenzierung auf ein Schema aus einer anderen OpenAPI Spezifizierung ist kein Problem. Somit muss die Änderung nur an einer Stelle erfolgen 🙂

Aber es gibt noch mehr Gründe, auf Spezifikationen wie OpenAPI zu setzen, wie z.B. die Tatsache, dass das Format sich mittlerweile zu einem Industriestandard entwickelt hat. Arbeitet man mit externen Partnern zusammen, ist es natürlich hilfreich, wenn ein solcher verwendet wird, da davon ausgegangen werden kann, dass professionelle Entwickler:innen vermutlich schon damit in Berührung gekommen sind. Toll ist an Formaten wie OpenAPI auch, dass das standardisierte Format es ermöglicht maschinengelesen zu werden.

Das macht es möglich, dass Tools wie Swagger (aus dem Swagger Projekt ist ursprünglich auch OpenAPI entstanden) z.B. einen Editor zur Verfügung stellen, der die Dokumentation validiert, oder eine UI, mit der die Dokumentation um einiges lesbarer wird und auch direkt Requests auf die API abgeschickt werden können. 

Hier nochmal ein Überblick der Vorteile von OpenAPI:

Ich möchte hier noch einmal betonen, dass OpenAPI nicht der einzige Standard zur Beschreibung von REST-Apis ist. Ein anderer Standard, der große Verbreitung genießt, wäre z.B. RAML. Auch dieser bringt viele der oben beschriebenen Vorteile mit. Falls du interessiert bist an einem direkten Vergleich der zwei, oder ein glühender Verfechter von RAML bist, schreib gerne einen Kommentar! 

Fazit und Ausblick

Wie ihr in dieser kurzen Einführung gesehen haben, ist es für alle Projektbeteiligten von großem Vorteil, wenn APIs sauber in einem standardisierten Format spezifiziert und dokumentiert werden. Wenn du mehr über OpenAPI erfahren willst, verweise ich an dieser Stelle auf die sehr ausführliche Dokumentation.