KI in API-Integrationen: wie man technische Dokumentation erstellt und pflegt

API-Dokumentation beginnt bei den Quellen, nicht beim Prompt

Wenn sich API-Dokumentation zusammen mit dem Code aktualisieren soll, sollte KI auf zwei Ebenen arbeiten: OpenAPI oder GraphQL als Quelle der Wahrheit sowie narrative Dokumentation wie Anleitungen, Quickstarts und Beschreibungen der Authentifizierung, wie Intellowork empfiehlt. Laut DIDWW ist es außerdem sinnvoll, das Modell mit zusätzlichen Hilfsdateien wie `llms.txt`, `llms-full.txt` und Links zu relevanten Seiten zu versorgen, anstatt sich auf eine einzelne Beschreibung ohne Kontext zu verlassen.

Diese Trennung ist wichtig, denn KI ordnet Inhalte gut, sollte aber den API-Vertrag nicht raten. In der Praxis bedeutet das, dass der Generator Endpunktnamen, Parameter, Datentypen, Antwortcodes und Schemata aus der OpenAPI-Definition extrahieren sollte, und erklärender Text von einem Menschen oder einem Agenten mit vollem Kontext ergänzt wird.

Wie man den Generierungsprozess gestaltet

Laut DIDWW muss dem Modell vor der Generierung der Dokumentation die Umgebung, der Authentifizierungsmodus, die Auslieferungsweise, die Programmiersprache und das verwendete SDK übergeben werden. Dieselbe Dokumentation empfiehlt, generierte Requests im Sandbox zu testen, bevor sie produktiv eingesetzt werden.

Ein praktischer Ablauf sieht so aus:

• Extrahiere den API-Vertrag aus OpenAPI oder GraphQL.
• Füge narrative Dokumentation hinzu, die Geschäftsszenarien und Autorisierung erklärt.
• Bitte die KI, fehlende Beschreibungen, Beispiele und Abschnitte für spezifische Zielgruppen zu erstellen.
• Überprüfe Beschreibungen anhand des Codes, der Tests und der Sandbox-Umgebung.
• Richte eine automatische Aktualisierung der Dokumentation nach Änderungen im Repository ein.

Laut den im Skills Directory beschriebenen Praktiken sollte jeder Dokumentationseintrag Signatur, Parameter, Antworten, Fehler, Statusangaben und mindestens ein realistisches Request/Response-Beispiel enthalten. Das erleichtert sowohl die manuelle Prüfung als auch die automatische Validierung durch den Generator.

Pflege: wo KI hilft und wo Kontrolle erforderlich ist

Der größte Nutzen von KI bei der Pflege der Dokumentation besteht darin, Lücken zwischen Code und Beschreibung zu erkennen und nach Änderungen an Endpunkten, Parametern oder Antwortformaten Aktualisierungen vorzuschlagen. Hostkey beschreibt einen Ansatz, bei dem API-Dokumentation als Pipeline aus separaten Stufen entsteht: Indexierung, Extraktion, Generierung, Validierung und Monitoring, und das LLM erhält bereits geordnete Daten und erzeugt daraus das finale Markdown.

Nach demselben Ansatz und den Praktiken des Skills Directory sollten diese drei Bedingungen eingehalten werden:

• Die KI darf Dokumentation nicht aus einem leeren Prompt schreiben, sondern muss von aktuellem Code und Vertrag ausgehen.
• Jede generierte Beschreibung ist mit Implementierung und Tests abzugleichen.
• Nach Änderungen an der API sollte der Generator nur die betroffenen Abschnitte aktualisieren und nicht das gesamte Portal neu schreiben.

Wo am häufigsten Fehler auftreten

Das häufigste Problem ist eine Diskrepanz zwischen der Beschreibung und dem tatsächlichen Verhalten eines Endpunkts. Wenn das Modell ein Beispiel erzeugt, ohne Statuscodes, Feldtypen oder Autorisierungsanforderungen zu prüfen, wird die Dokumentation optisch ansprechend, aber operativ unbrauchbar. DIDWW betont die Notwendigkeit, technischen Kontext bereitzustellen und generierte Requests im Sandbox zu testen.

Ein zweites Risiko ist das Vermischen der Referenz- mit der Beschreibungs-Ebene. Intellowork unterscheidet maschinenlesbare Dokumentation, also die OpenAPI/GraphQL-Spezifikation, von narrativer Dokumentation, also Anleitungen und Erklärungen. Diese Trennung hilft, Situationen zu vermeiden, in denen KI „schönen" Text an einen fehlerhaften Vertrag anhängt.

Lub System unterstützt B2B-Unternehmen bei der Einführung von KI, Automatisierung und IT-Lösungen - von der Strategie bis zur Umsetzung. Mehr zu unseren Leistungen oder Kontakt aufnehmen.