API-Dokumentation mit KI erstellen und am Code prüfen

Das Problem

Ihre Firma bietet eine Schnittstelle an, oder sie nutzt eine, die intern entwickelt wurde. Eine Schnittstelle, auf Englisch API, ist eine Art Steckdose für Programme: Ein System kann darüber Daten abfragen oder senden. Wer sie nutzen will, braucht eine Beschreibung: Welche Adressen gibt es, welche Angaben muss man mitschicken, was kommt zurück, welche Fehler sind möglich?

In der Praxis ist die Beschreibung oft veraltet oder fehlt. Der Entwickler weiss, wie es geht, schreibt aber ungern Dokumentation. Externe Partner stellen immer wieder dieselben Fragen. Und wenn die Beschreibung vom tatsächlichen Verhalten abweicht, gibt es Fehler, die schwer zu finden sind.

KI kann Dokumentationen schnell entwerfen, wenn sie den Code oder eine technische Beschreibung kennt. Das Risiko: Sie formuliert überzeugend, auch wenn etwas nicht stimmt. Deshalb gilt der Grundsatz: Die Dokumentation wird am echten Verhalten geprüft, nicht nur gelesen.

So lösen Sie es mit KI – Schritt für Schritt

1. Klären Sie die Zielgruppe. Wer liest die Doku? Interne Entwickler, externe Partner, Einsteigende? Das bestimmt Ton und Tiefe.
2. Sammeln Sie die Quellen. Der Code der Schnittstelle, vorhandene Beschreibungen, Testfälle, Beispielaufrufe. Eine maschinenlesbare Beschreibung wie OpenAPI ist ideal, falls vorhanden.
3. Bereinigen Sie die Eingaben. Entfernen Sie Schlüssel, Passwörter, interne Adressen und echte Kundendaten. Verwenden Sie erfundene Beispieldaten. Siehe Quellcode und Daten in KI-Werkzeugen.
4. Lassen Sie die KI einen Entwurf erstellen. Mit dem Auftrag unten pro Schnittstellen-Endpunkt: Zweck, Adresse, Methode, Parameter, Beispielanfrage, Beispielantwort, Fehlercodes.
5. Prüfen Sie den Entwurf gegen den Code. Stimmen Namen, Datentypen, Pflichtfelder, Standardwerte? Eine zweite Person liest mit.
6. Testen Sie die Beispiele. Führen Sie jede Beispielanfrage gegen eine Testumgebung aus. Entspricht die Antwort der Doku? Wenn nicht, korrigieren Sie die Doku oder den Code.
7. Dokumentieren Sie Fehlerfälle. Welche Fehlercodes kommen vor, was bedeuten sie, was soll der Aufrufer tun? Auch hier: aus dem echten Verhalten.
8. Pflegen Sie die Doku mit dem Code. Jede Änderung an der Schnittstelle aktualisiert die Doku. Automatisierte Tests, die die Beschreibung prüfen, helfen, falls es sie gibt.

Vorlage zum Kopieren

Fügen Sie nur bereinigten Code oder Beschreibungen ein, ohne Schlüssel und echte Daten.

Erstelle aus dem folgenden bereinigten Quellcode bzw. der folgenden Beschreibung einer Schnittstelle (API) eine Dokumentation für Entwickler eines Schweizer KMU: [Code oder Beschreibung einfügen, ohne Geheimnisse und echte Daten].
Gliedere pro Endpunkt: 1. Zweck in einem Satz, 2. Adresse und HTTP-Methode, 3. Parameter in einer Tabelle (Name, Typ, Pflicht, Beschreibung), 4. Beispielanfrage mit erfundenen Daten, 5. Beispielantwort, 6. Fehlercodes mit Bedeutung und empfohlenem Vorgehen, 7. Hinweise (Authentifizierung nur beschreiben, keine Schlüssel nennen).
Verwende nur Informationen, die im Code oder in der Beschreibung stehen. Markiere Stellen, bei denen das Verhalten aus dem Code nicht eindeutig hervorgeht, mit [prüfen]. Erfinde keine Parameter, Felder oder Fehlercodes.

Die Entwicklerin prüft jeden Endpunkt am laufenden System und führt die Beispielanfragen aus.

Was in eine API-Doku gehört

Worauf Sie achten müssen

• Schlüssel und Zugangsdaten: Sie gehören weder in die Doku noch in KI-Eingaben. Wenn doch einer in eine Eingabe gelangt ist, ersetzen Sie ihn sofort.
• Erfundene Felder: KI ergänzt gern «übliche» Parameter, die es nicht gibt. Prüfen Sie jedes Feld am Code.
• Abweichung zwischen Code und Verhalten: Manchmal verhält sich die Schnittstelle anders, als der Code vermuten lässt, etwa wegen Konfiguration. Deshalb braucht es Tests.
• Sicherheit: Dokumentation kann Angriffspunkte verraten. Prüfen Sie, welche Details öffentlich sein dürfen.
• Lizenz und Urheberrecht: Wenn Sie Code mit KI bearbeiten, beachten Sie die Regeln Ihres Betriebs und die Bedingungen des Werkzeugs.
• Versionierung: Notieren Sie, für welche Version der Schnittstelle die Doku gilt, und ändern Sie sie bei Änderungen am Code.

Ein Beispiel aus der Praxis

Ein Beispiel: Ein Softwarehaus in Bern bietet seinen Kunden eine Schnittstelle zum Abrufen von Rechnungsdaten an.

Vorher: Die Beschreibung ist eine zwei Jahre alte PDF-Datei. Zwei Kunden melden Fehler, weil ein Feld inzwischen anders heisst und ein neuer Fehlercode existiert. Der Support verbringt Stunden mit Rückfragen.

Nachher: Der Entwickler lässt aus dem bereinigten Code einen Doku-Entwurf erstellen und prüft jeden Endpunkt mit Testaufrufen. Dabei fallen drei Abweichungen auf, die er korrigiert. Die Beispiele sind getestet, die Doku trägt die Versionsnummer. Seither fragen Kunden seltener nach.

So hilft Ihnen Alpasana

Der Kurs KI für Developer mit Claude und Codex von absofort behandelt LLM-Grundlagen, Tokens, Kontext, Grenzen und Datenschutz, Codegenerierung, Debugging, Refactoring und Review sowie das Delegieren von Aufgaben und das Verifizieren der Ergebnisse. Claude, Claude Code, Claude API und Codex sind Kursgegenstände.

Dazu gehören ein Entwickler-Playbook mit Prompts, Review-Regeln, Tests und Datenschutzgrenzen, ein Praxisprojekt, ein Abschlussquiz, eine KI-geprüfte Praxisaufgabe und ein verifizierbares Zertifikat.

Häufige Fragen

Was ist OpenAPI?

Ein verbreitetes Format, um eine Schnittstelle maschinenlesbar zu beschreiben. Aus einer solchen Beschreibung lassen sich Dokumentation und Tests erzeugen. Weitere Informationen bietet die OpenAPI Specification. Für den Einstieg genügt eine saubere Textbeschreibung.

Kann die KI die Doku automatisch aktuell halten?

Teilweise, wenn sie bei jeder Änderung am Code neu erzeugt und geprüft wird. Ohne Prüfung schleichen sich Fehler ein. Besser ist ein Ablauf, bei dem Änderungen die Doku und Tests mit aktualisieren.

Wie gehe ich mit Beispielantworten um, die echte Daten enthalten?

Ersetzen Sie sie durch erfundene Daten. Beispiele mit echten Namen, Adressen oder Beträgen gehören nicht in eine Doku, die weitergegeben wird.