API-Dokumentation erstellen: Aufbau, Beispiel und Werkzeuge
Eine gute API-Dokumentation entscheidet darüber, ob Partner, Kunden und Ihr eigenes Team eine Schnittstelle in einer Stunde anbinden oder in drei Wochen. Dieser Ratgeber zeigt, aus welchen Teilen eine API-Dokumentation besteht, wie ein Beispiel mit OpenAPI aussieht, welche Gliederung sich als Vorlage bewährt, welche Werkzeuge es gibt und wie die Dokumentation aktuell bleibt, wenn sich die Schnittstelle weiterentwickelt.
Warum die Dokumentation über den Erfolg einer API entscheidet
Eine Schnittstelle ist ein Produkt, dessen Nutzer Entwicklerinnen und Entwickler sind. Sie lesen keine Broschüre, sondern suchen drei Dinge: wie sie sich anmelden, wie der erste Aufruf aussieht und was ein Fehler bedeutet. Fehlt eine dieser Antworten, landen Fragen im Support, Integrationen dauern länger, und Partner bauen um Ihre API herum statt mit ihr.
Wenn Sie eine API anbieten, weil Kunden Daten aus Ihrem Produkt abrufen sollen, ist eine gute Dokumentation zudem eine Pflichtaufgabe geworden: Der Data Act verlangt bei vernetzten Produkten Zugangswege zu Nutzungsdaten, und eine dokumentierte Schnittstelle ist dafür der naheliegende Weg.
Die Bausteine einer guten API-Dokumentation
- Überblick. Was die API leistet, für wen sie gedacht ist, Basis-URL, Umgebungen für Test und Produktion.
- Schnellstart. Von der Registrierung bis zum ersten erfolgreichen Aufruf in wenigen Schritten, mit kopierbarem Beispiel.
- Authentifizierung. Verfahren, etwa OAuth 2.0 oder API-Schlüssel, Gültigkeit von Tokens, Berechtigungsumfänge.
- Referenz. Jeder Endpunkt mit Methode, Pfad, Parametern, Anfrage- und Antwortschema, Beispielen und möglichen Statuscodes.
- Fehlerreferenz. Einheitliches Fehlerformat, Liste der Fehlercodes mit Ursache und Abhilfe.
- Konzepte. Paginierung, Filter, Idempotenz, Ratenbegrenzung, Zeitzonen, Versionierung.
- Webhooks und Ereignisse. Welche Ereignisse es gibt, wie sie signiert sind, wie oft zugestellt wird.
- Changelog. Änderungen mit Datum, Hinweise auf Breaking Changes und Abkündigungen mit Frist.
Der Standard: OpenAPI
Für HTTP-APIs hat sich die OpenAPI-Spezifikation durchgesetzt. Sie definiert eine standardisierte, programmiersprachenunabhängige Beschreibung von HTTP-APIs, mit der Menschen und Computer die Fähigkeiten eines Dienstes erkennen können, ohne Quellcode, zusätzliche Dokumentation oder Netzwerkverkehr zu untersuchen. Die zuletzt veröffentlichte Version ist 3.2.1 vom 10. September 2026 (OpenAPI Specification, abgerufen am 12. November 2026).
Die Spezifikation ging aus der Swagger-Spezifikation hervor, die SmartBear 2015 einbrachte; seit 2016 betreut die OpenAPI Initiative als offenes Projekt der Linux Foundation die Weiterentwicklung (OpenAPI Initiative, FAQ, abgerufen am 12. November 2026). Deshalb begegnen Ihnen beide Namen: OpenAPI für das Format, Swagger für eine Reihe von Werkzeugen.
Für Fehlerantworten gibt es ebenfalls einen Standard. RFC 9457 der IETF definiert „Problem Details" als maschinenlesbares Format für Fehler in HTTP-Antworten und ersetzt RFC 7807 (RFC 9457, Problem Details for HTTP APIs, abgerufen am 12. November 2026). Wer ihn nutzt, erspart Partnern das Raten, wie ein Fehler aufgebaut ist.
Ein Beispiel: ein Endpunkt in OpenAPI
So sieht die Beschreibung eines einfachen Endpunkts aus, der einen Auftrag abruft. Aus genau dieser Datei erzeugen Werkzeuge eine lesbare Referenzseite, Testaufrufe und Client-Bibliotheken.
openapi: 3.1.0
info:
title: Auftrags-API
version: 1.4.0
paths:
/auftraege/{id}:
get:
summary: Einen Auftrag abrufen
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
"200":
description: Der Auftrag
content:
application/json:
schema: { $ref: "#/components/schemas/Auftrag" }
"404":
description: Auftrag nicht gefunden
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
Zur Referenz gehören gute Beispiele: echte, plausible Werte statt „string", Datumsangaben im Format, das die API wirklich liefert, und für jeden Fehlerfall ein Beispiel der Antwort. Die Beschreibungen schreiben Sie für Menschen, nicht für den Generator.
Eine Vorlage für die Gliederung
| Abschnitt | Inhalt | Format |
|---|---|---|
| Einführung | Zweck, Zielgruppe, Umgebungen, Support-Weg | Text |
| Schnellstart | Zugang, Token, erster Aufruf, erwartete Antwort | Text mit Beispielen |
| Authentifizierung | Verfahren, Scopes, Token-Lebensdauer, Rotation | Text |
| Referenz | Endpunkte, Schemas, Statuscodes | Aus OpenAPI erzeugt |
| Fehler | Problem-Details-Format, Fehlercodes, Abhilfe | Text und OpenAPI |
| Leitfäden | Typische Abläufe, etwa „Bestellung anlegen und verfolgen" | Text mit Beispielen |
| Webhooks | Ereignisse, Signaturprüfung, Wiederholungen | Text und Schemas |
| Changelog und Versionen | Änderungen, Abkündigungen, Fristen | Text |
Werkzeuge für die API-Dokumentation
Für die Darstellung einer OpenAPI-Beschreibung gibt es freie und kommerzielle Werkzeuge, darunter Swagger UI, Redoc, Scalar, Stoplight und Postman. Wichtiger als das Werkzeug sind drei Eigenschaften: Die Seite wird automatisch aus der Beschreibung im Repository erzeugt, sie erlaubt Testaufrufe gegen eine Testumgebung, und erklärende Texte lassen sich neben der Referenz pflegen. Für ereignisgesteuerte Schnittstellen über Message-Broker gibt es mit AsyncAPI ein vergleichbares Format.
Wer nicht öffentlich dokumentieren will, veröffentlicht die Dokumentation hinter einer Anmeldung im Partnerportal. Auch dann gilt: eine Quelle, aus der alles erzeugt wird, statt PDF-Dateien, die nach dem ersten Release veralten.
Dokumentation, die aktuell bleibt
- Im Repository. Die OpenAPI-Datei liegt neben dem Code und wird mit ihm versioniert.
- In der Pipeline geprüft. Ein Linter prüft Stil und Vollständigkeit, Vertragstests prüfen, ob die Implementierung der Beschreibung entspricht.
- Versioniert. Breaking Changes nur mit neuer Hauptversion und angekündigter Frist für die alte.
- Mit Verantwortlichen. Jede Änderung an der API hat jemanden, der die Dokumentation freigibt.
- Gemessen. Häufige Support-Fragen zeigen, welche Stelle der Dokumentation fehlt.
Wie wir Sie unterstützen
Wir entwickeln Schnittstellen mit Design first und liefern die Dokumentation als Teil der Leistung, nicht als Nachtrag. Für bestehende APIs schreiben wir die fehlende OpenAPI-Beschreibung, ergänzen Schnellstart, Leitfäden und Fehlerreferenz und richten die automatische Veröffentlichung ein. Mehr zu unserer Arbeit an Schnittstellen finden Sie auf der Seite Schnittstellenprogrammierung; wenn die API Teil eines größeren Systems ist, lohnt der Blick auf Individualsoftware und Kundenportale. Quellcode und Dokumentation gehören Ihnen, Hosting in der EU ist Standard, und für den schriftlich vereinbarten Umfang erhalten Sie einen Festpreis.
Häufige Fragen
Was ist eine API-Dokumentation?
Die Beschreibung einer Programmierschnittstelle für die Menschen und Programme, die sie nutzen: welche Endpunkte es gibt, welche Daten sie erwarten und liefern, wie man sich anmeldet, welche Fehler auftreten und wie man in wenigen Minuten den ersten erfolgreichen Aufruf schafft. Sie besteht meist aus einer maschinenlesbaren Beschreibung, etwa nach OpenAPI, und erklärenden Texten.
Was ist der Unterschied zwischen OpenAPI und Swagger?
OpenAPI ist die Spezifikation, also das Format, in dem eine HTTP-API beschrieben wird. Sie entstand aus der Swagger-Spezifikation, die 2015 an die OpenAPI Initiative unter dem Dach der Linux Foundation gegeben wurde. Swagger heißt heute vor allem eine Familie von Werkzeugen, etwa Swagger UI zur Darstellung und Swagger Editor zum Schreiben solcher Beschreibungen.
Welche OpenAPI-Version sollten wir verwenden?
Für neue APIs die aktuelle 3er-Version. Die zuletzt veröffentlichte Fassung ist 3.2.1 vom 10. September 2026. Prüfen Sie vorher, ob Ihre Werkzeuge für Darstellung, Tests und Codegenerierung die gewählte Version unterstützen; viele Werkzeuge hinken der Spezifikation einige Monate hinterher.
Code first oder Design first?
Bei Design first schreiben Sie zuerst die OpenAPI-Beschreibung und stimmen sie mit den Nutzern ab, danach wird implementiert. Bei Code first erzeugt der Code die Beschreibung. Für öffentliche Schnittstellen und Partner-APIs empfehlen wir Design first, weil eine Änderung an der Beschreibung weniger Aufwand verursacht als eine Änderung am fertigen Code. Für interne APIs ist Code first mit Prüfung in der Build-Pipeline oft ausreichend.
Wie halten wir die Dokumentation aktuell?
Indem sie Teil des Codes ist: Die OpenAPI-Datei liegt im Repository, jeder Pull Request, der die API ändert, ändert auch die Beschreibung, und automatische Tests prüfen, ob die Implementierung der Beschreibung entspricht. Ein Changelog mit Datum und Hinweisen zu Breaking Changes gehört dazu.
Schreibt DT Nova API-Dokumentationen für bestehende Schnittstellen?
Ja. Wir analysieren eine bestehende API, schreiben die OpenAPI-Beschreibung, ergänzen Einstiegsanleitung, Beispiele und Fehlerreferenz und richten die Veröffentlichung und die automatische Prüfung ein. Die Dokumentation liegt danach in Ihrem Repository und gehört Ihnen.
Schriftliches Angebot anfordern
Beschreiben Sie in wenigen Zeilen, was Sie brauchen. Innerhalb eines Werktags erhalten Sie ein schriftliches Angebot: Umfang, Zeitplan und Festpreis oder Stundenschätzung. Die Anfrage ist unverbindlich.