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.
![](https://heise.cloudimg.io/width/610/q85.png-lossy-85.webp-lossy-85.foil1/_www-heise-de_/imgs/18/3/1/1/2/4/5/4/ct0921openapifu_albert_hulm_114402_jam_a_16zu91-0070f9731a195740.jpeg)
(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".
Das war die Leseprobe unseres heise-Plus-Artikels "OpenAPI-Dokumentation: Große APIs nach dem Standard OpenAPI dokumentieren ". Mit einem heise-Plus-Abo können sie den ganzen Artikel lesen und anhören.