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.

Lesezeit: 5 Min.
In Pocket speichern
vorlesen Druckansicht Kommentare lesen

(Bild: Albert Hulm)

Von
  • Manuel Ottlik
Inhaltsverzeichnis

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.

Mehr zum Thema API

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.

  • Zugriff auf alle Inhalte von heise+
  • exklusive Tests, Ratgeber & Hintergründe: unabhängig, kritisch fundiert
  • c't, iX, MIT Technology Review, Mac & i, Make, c't Fotografie direkt im Browser lesen
  • einmal anmelden – auf allen Geräten lesen - monatlich kündbar
  • erster Monat gratis, danach monatlich 12,95 €
  • Wöchentlicher Newsletter mit persönlichen Leseempfehlungen des Chefredakteurs
GRATIS-Monat beginnen Jetzt GRATIS-Monat beginnen Mehr Informationen zu heise+