Dokumentationsverpackung
Große APIs nach dem Standard OpenAPI dokumentieren
Eine OpenAPI-Dokumentation beschreibt die Endpunkte eines REST-APIs. Wer große APIs programmiert, verstrickt sich aber schnell in einer riesigen und unhandlichen YAML-Datei. Zum Glück gibt es Werkzeuge, die große Dokumentationen sinnvoll aufteilen und Komponenten wiederverwenden.
APIs sind das Herzstück vieler servergestützter Anwendungen. Sie beliefern Webseiten, Desktop-Anwendungen und mobile Apps mit Daten. Für APIs, die auf dem Web-Protokoll HTTP basieren, hat sich das Paradigma REST durchgesetzt, das wir bereits ausführlich beschrieben haben [1]. Ein REST-Endpunkt setzt sich aus einem HTTP-URI (zum Beispiel https://api.example.org/things/) und der HTTP-Methode (GET, POST, PUT, PATCH, DELETE) zusammen. Die HTTP-Methode beeinflusst, was mit den Daten passiert. Mit GET bezieht man Daten, DELETE löscht einen Datensatz.
Die Funktionsweise eines REST-APIs könnten sich die Nutzer fast selbst erschließen. Zum guten Stil als API-Entwickler gehört es aber, ein API in einer für Menschen und Maschinen lesbaren Form (in einer Interface Description Language, IDL) zu dokumentieren. Für REST-APIs ist OpenAPI das Dokumentationsformat der Wahl – ausführlich haben wir das in [2] bereits vorgestellt. Geschrieben in YAML oder JSON, erklärt eine OpenAPI-Dokumentation jeden Endpunkt: Das OpenAPI-Dokument verrät, welche Datenstruktur man ans API senden muss und welche Antwort man erwarten kann. Das Schöne an OpenAPI: Weil es maschinenlesbar ist, gibt es viele Werkzeuge, die die Dokumentation einlesen und damit Nützliches anstellen können. OpenAPI-Tools generieren Testfälle für Integrationstests, ansehnliche Dokumentationen für Nutzer oder sogar Gerüste des Programmcodes für Clients und Server. Eine Auflistung nützlicher Werkzeuge aus dem OpenAPI-Kosmos finden Sie in der Liste „Awesome OpenAPI“ über ct.de/yqw4.