Zum Inhalt springen
DT Nova
Ratgeber

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

  1. Überblick. Was die API leistet, für wen sie gedacht ist, Basis-URL, Umgebungen für Test und Produktion.
  2. Schnellstart. Von der Registrierung bis zum ersten erfolgreichen Aufruf in wenigen Schritten, mit kopierbarem Beispiel.
  3. Authentifizierung. Verfahren, etwa OAuth 2.0 oder API-Schlüssel, Gültigkeit von Tokens, Berechtigungsumfänge.
  4. Referenz. Jeder Endpunkt mit Methode, Pfad, Parametern, Anfrage- und Antwortschema, Beispielen und möglichen Statuscodes.
  5. Fehlerreferenz. Einheitliches Fehlerformat, Liste der Fehlercodes mit Ursache und Abhilfe.
  6. Konzepte. Paginierung, Filter, Idempotenz, Ratenbegrenzung, Zeitzonen, Versionierung.
  7. Webhooks und Ereignisse. Welche Ereignisse es gibt, wie sie signiert sind, wie oft zugestellt wird.
  8. 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

AbschnittInhaltFormat
EinführungZweck, Zielgruppe, Umgebungen, Support-WegText
SchnellstartZugang, Token, erster Aufruf, erwartete AntwortText mit Beispielen
AuthentifizierungVerfahren, Scopes, Token-Lebensdauer, RotationText
ReferenzEndpunkte, Schemas, StatuscodesAus OpenAPI erzeugt
FehlerProblem-Details-Format, Fehlercodes, AbhilfeText und OpenAPI
LeitfädenTypische Abläufe, etwa „Bestellung anlegen und verfolgen"Text mit Beispielen
WebhooksEreignisse, Signaturprüfung, WiederholungenText und Schemas
Changelog und VersionenÄnderungen, Abkündigungen, FristenText

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

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.

Kontakt · Alle Leistungen

Angebot anfragen