Eine API-Dokumentation beschreibt, wie eine Schnittstelle benutzt wird: welche Endpunkte es gibt, welche Daten sie erwarten und was sie zurückgeben. Heute liegt sie meist als maschinenlesbare Datei nach dem Standard OpenAPI vor, aus der sich eine lesbare Seite erzeugen lässt.
- API-Dokumentation
Die Beschreibung aller Endpunkte, Parameter, Anmeldeverfahren und Antworten einer Schnittstelle, oft als OpenAPI-Datei.
Beispiel: „Aus der API-Dokumentation des Anbieters ließ sich der Client für die Anbindung automatisch erzeugen.“Verwandt: OpenAPI, der Standard für das Format der Beschreibung, und Swagger, die bekannteste Werkzeugfamilie dafür.
Was in eine API-Dokumentation gehört
Jeder Endpunkt mit Methode, Parametern, Beispiel für Anfrage und Antwort sowie den möglichen Fehlern. Dazu die Anmeldung, die Grenzen für Anfragen, die Pagination und die Version.
Am meisten helfen Beispiele, die sich direkt kopieren lassen. Eine Dokumentation, die nur Felder aufzählt, lässt beim Ausprobieren die meisten Fragen offen.
OpenAPI und Swagger
OpenAPI beschreibt eine Schnittstelle in einer Datei im Format JSON oder YAML. Aus dieser Datei erzeugen Werkzeuge wie Swagger UI aus der Familie Swagger oder Redoc eine Seite, auf der sich jeder Endpunkt im Browser ausprobieren lässt, und Generatoren schreiben fertige Clients in vielen Sprachen.
Manche Frameworks erzeugen die Datei selbst aus dem Code, FastAPI etwa aus den Typangaben. Dann bleibt die Dokumentation automatisch auf dem Stand der Schnittstelle.
API-Dokumentation und KI
Sprachmodelle und Agenten lesen OpenAPI-Dateien ebenso gut wie Menschen. Eine sauber beschriebene Schnittstelle lässt sich deshalb leichter an KI-Werkzeuge anbinden, die dann selbst entscheiden, welchen Endpunkt sie aufrufen.