OpenAPI-Dokumentation: Große APIs nach dem Standard OpenAPI dokumentieren
Wer große APIs programmiert, verstrickt sich schnell in einer YAML-Datei. Es gibt Tools, die Dokumentationen sinnvoll aufteilen und Komponenten wiederverwenden.
(Bild: Albert Hulm)
- Manuel Ottlik
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. 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.
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".
Immer mehr Wissen. Das digitale Abo für IT und Technik.
Java 22 vorgestellt: Update reduziert Boilerplate-Code
Wärmepumpe simpel und effektiv: Über die Rolle von Dämmung, Solar und Co.
Boox Note Air3 C im Test: Hybrid-Tablet mit farbigem E-Paper-Display
OpenCore Legacy Patcher: Wie Sie alte Macs mit jungem macOS aufbrezeln
High-End-Smartphones im Kameravergleich: Wettkampf um die beste Bildqualität
Smart Generator von Ecoflow im Test
Immer mehr Wissen. Das digitale Abo für IT und Technik.
Java 22 vorgestellt: Update reduziert Boilerplate-Code
Wärmepumpe simpel und effektiv: Über die Rolle von Dämmung, Solar und Co.
Boox Note Air3 C im Test: Hybrid-Tablet mit farbigem E-Paper-Display
OpenCore Legacy Patcher: Wie Sie alte Macs mit jungem macOS aufbrezeln
High-End-Smartphones im Kameravergleich: Wettkampf um die beste Bildqualität