API-Dokumentation mit KI-Agent und Apidog CLI erstellen

Die API-Dokumentation ist die Aufgabe, bei der sich alle einig sind, dass sie wichtig ist, aber niemand die Verantwortung dafür übernehmen möchte. Ein neuer Endpunkt wird ausgeliefert, die Referenz hinkt eine Woche hinterher, und der Leitfaden für den Einstieg beschreibt einen Authentifizierungsfluss, den Sie vor zwei Sprints ersetzt haben. Die Arbeit ist real, aber sie ist repetitiv und lässt sich leicht aufschieben.

Diese Kombination (wichtig, repetitiv, aufschiebbar) ist genau das, wofür ein KI-Agent gut ist. Wenn Ihr Agent einen Terminalbefehl ausführen kann, kann er Endpunkte verfassen, die erklärenden Anleitungen dazu schreiben und eine Dokumentationsseite veröffentlichen – alles auf Basis einer Anfrage in einfacher Sprache. Die Apidog CLI macht dies möglich: Jede Dokumentationsaktion ist ein skriptfähiger Befehl mit strukturierter JSON-Ausgabe, die ein Agent lesen und darauf reagieren kann.

Warum die CLI, nicht die GUI oder ein MCP-Server

Es gibt drei Möglichkeiten, wie ein Agent Ihre API-Dokumentation beeinflussen kann, und sie lösen unterschiedliche Probleme. Die richtige Unterscheidung zu treffen, macht den Unterschied aus, ob Sie gegen Ihre Tools ankämpfen oder das richtige für die Aufgabe verwenden.

Ein MCP-Server ist ausgezeichnet, wenn Sie möchten, dass ein Agent Ihre API-Definition liest und Client-Code dagegen generiert. Der Cursor Doc-through-MCP-Fluss ist das kanonische Beispiel. Aber das ist das Gegenteil von dem, was wir hier wollen. Wir wollen, dass der Agent die Dokumentation produziert: Endpunkte erstellen, Markdown-Anleitungen verfassen und eine Seite veröffentlichen.

Dafür gewinnt die CLI in dreifacher Hinsicht. Sie ist deterministisch: Derselbe Befehl erzeugt dasselbe Ergebnis. Sie ist skriptfähig: Der gesamte Fluss lässt sich in CI integrieren. Und sie gibt bei jedem Aufruf JSON zurück, einschließlich eines `agentHints.nextSteps`-Feldes, das dem Agenten mitteilt, was er als Nächstes tun kann. Dieser letzte Punkt ist wichtiger, als es klingt: Er bedeutet, dass der Agent seinen Weg nicht errät, sondern den Vorschlägen der CLI folgt.

Die Umgebung des Agenten einrichten

Installieren Sie die CLI und authentifizieren Sie sich einmalig. Unser Installationsleitfaden behandelt Node-Versionen und PATH; der Authentifizierungsleitfaden behandelt Tokens und CI-Secrets.

npm install -g apidog-cli
apidog login --with-token <TOKEN>

Holen Sie sich den Token aus der Apidog-App unter Benutzeravatar → Kontoeinstellungen → API-Zugriffstoken. Er wird nach dem Login lokal gespeichert, sodass der Agent ihn nicht bei jedem Aufruf weitergibt.

Jeder Schreibvorgang läuft gegen eine Projekt-ID, die Sie in den Projekteinstellungen → Basiseinstellungen finden oder indem Sie ausführen:

apidog project list

Jeder Coding-Agent, der Shell-Befehle ausführen kann, funktioniert hier: Claude Code, Cursor, Codex und andere. Der CLI ist es egal, welcher Agent sie aufruft; es ist ihr nur wichtig, dass die Befehle und Payloads korrekt sind. Was uns zu der einen Regel bringt, die das Ganze zuverlässig macht.

Das Schreibritual, dem ein Agent folgen muss

Dokumentationsbefehle, die Ressourcen erstellen, nehmen eine JSON-Datei entgegen. Ihr Agent sollte diese JSON niemals aus dem Gedächtnis von Hand erstellen. Von Modellen erfundene Feldnamen sind die Hauptursache für fehlgeschlagene Ausführungen. Die CLI liefert das genaue Schema für jeden Schreibvorgang, und die korrekte Reihenfolge ist immer die gleichen vier Schritte:

# 1. Fragen Sie die CLI, wie die Payload aussieht
apidog cli-schema get doc-create

# 2. Erzeugen Sie die JSON-Datei aus diesem Schema

# 3. Validieren Sie vor dem Schreiben (fängt ein fehlendes Feld lokal ab)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Erst jetzt den eigentlichen Befehl ausführen
apidog doc create --project <projectId> --file ./doc.json

Integrieren Sie diese Schleife in die Anweisungen des Agenten. Es verwandelt "das Modell hat ein Feld erfunden" in "der Validator hat es auf meiner Maschine abgelehnt", was den Unterschied zwischen einem sauberen Lauf und einem fehlgeschlagenen Build ausmacht. Hier ist ein Regelblock, den Sie direkt in den System-Prompt eines Agenten oder in eine `CLAUDE.md` / `.cursorrules`-Datei einfügen können:

Apidog CLI-Regeln:
- Schreiben Sie niemals eine JSON-Payload von Hand. Führen Sie zuerst `apidog cli-schema get <key>` aus und erstellen Sie daraus das Schema.
- Validieren Sie jede Datei mit `apidog cli-schema validate <key> --file <path>` vor jedem Erstellen oder Aktualisieren.
- Übergeben Sie bei Schreibbefehlen immer `--project <id>`.
- Lesen Sie das Feld `agentHints.nextSteps` in jeder JSON-Antwort, um den nächsten Befehl zu wählen.
- Wenn ein Schreibvorgang aufgrund von Berechtigungen blockiert wird, halten Sie an und fragen Sie den Menschen; wählen Sie keinen Workaround.

Diese fünf Zeilen sind es, die einen Agenten, der zuverlässig Dokumente versendet, von einem trennen, der Payloads in eine Wand rät.

Schritt 1: Die Referenz aus Endpunkten und Schemata erstellen

In Apidog wird Ihre API-Referenz aus den Endpunkten und Datenschemata im Projekt generiert. Die erste Aufgabe des Agenten besteht also darin, diese zu erstellen. Angenommen, Sie sagen ihm:

„Fügen Sie einen `POST /refunds`-Endpunkt hinzu, der eine Bestell-ID und einen Betrag entgegennimmt, und dokumentieren Sie dessen Erfolgs- und Validierungsfehler-Antworten.“

Der Agent erstellt zuerst das wiederverwendbare Datenmodell, dann den Endpunkt, der darauf verweist. `apidog cli-schema get schema-create` zeigt, dass ein Datenschema einen `name` und ein standardmäßiges `jsonSchema`-Objekt benötigt. Also schreibt der Agent etwas wie `refund-schema.json`:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}

Validieren und erstellen:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Nun der Endpunkt. Das `endpoint-create`-Schema erfordert `method` und `path` und ermöglicht es Ihnen, das soeben erstellte Datenmodell mit einem `$ref` im Format `#/definitions/{schemaId}` zu referenzieren. Der Agent schreibt `refunds-endpoint.json`:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

Die Referenzdokumentation für `/refunds` existiert nun, gerendert aus derselben Definition, die Ihr Team bearbeitet. Es gibt keinen separaten "Dokumente exportieren"-Schritt für die Referenz; sie ist live im Projekt, sobald der Endpunkt landet. Das ist der Vorteil einer Schema-First-Quelle: Die Referenz kann nicht abweichen, weil sie das Schema ist.

Schritt 2: Die Anleitungen schreiben, nicht nur die Referenz

Eine aus Schemas generierte Referenz ist nur die Hälfte einer guten Dokumentation. Die andere Hälfte ist Prosa: eine Einstiegsseite, eine Authentifizierungs-Walkthrough, ein Migrationshinweis. In Apidog leben diese als Markdown-Dokumente im Docs-Baum des Projekts, verwaltet durch die Befehlsgruppe `doc`.

Das `doc-create`-Schema benötigt nur einen `name`; `content` enthält das Markdown, und `folderId` platziert es im Baum (`0` ist das Stammverzeichnis). Eine vom Agenten entworfene Schnellstartanleitung wird also zu `quickstart.json`:

{
  "name": "Quickstart: Your first refund",
  "content": "# Schnellstart\n\nDieser Leitfaden führt Sie in fünf Minuten vom API-Schlüssel zu Ihrer ersten Rückerstattung...",
  "folderId": 0
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

Hier verdient der Agent sein Geld. Bitten Sie ihn, "einen Schnellstart zu schreiben, der einen neuen Entwickler vom API-Schlüssel bis zur ersten Rückerstattung führt", und er entwirft das Markdown, verpackt es in die vom Schema erwartete Payload, validiert und erstellt das Dokument. Kein Browser, kein Kopieren und Einfügen. Da der Inhalt nur ein String-Feld ist, kann der Agent einen so langen oder detaillierten Leitfaden schreiben, wie die Aufgabe es erfordert.

Schritt 3: Die Docs-Seite veröffentlichen

Mit der Referenz und den Anleitungen kann der Agent auch vom Terminal aus veröffentlichen. Zwei Befehlsgruppen erledigen dies, und eine Namensunterscheidung bringt die Leute ständig durcheinander:

• `doc`: ein Markdown-Dokument innerhalb des API-Baums des Projekts (was Sie in Schritt 2 erstellt haben).
• `docs-site`: die gehostete, öffentliche Dokumentationsseite.
• `shared-doc`: ein teilbarer Link, um ihn einem Partner zu geben, keine vollständige Website.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Verwenden Sie `docs-site`, wenn Sie eine öffentliche Website vom Terminal aus definieren möchten, und `shared-doc`, wenn Sie nur einen Link zum Versenden benötigen. Da beides Befehle sind, wird die Veröffentlichung zu einem skriptgesteuerten Schritt, den der Agent nach jeder Dokumentationsänderung ausführt; die gehostete Website spiegelt das Update wider, sobald der Befehl zurückkehrt.

Schritt 4 (optional): Eine portable Kopie exportieren

Manchmal möchte man die Dokumente als Datei: eine HTML-Seite, um sie an anderer Stelle zu hosten, Markdown für einen statischen Website-Generator oder OpenAPI, um sie nachgelagerten Systemen zur Verfügung zu stellen. Der `export`-Befehl erzeugt alle drei:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

Wenn Ihr Projekt mehrere Dienste enthält und Sie nur einen Teil davon dokumentiert haben möchten, zeigt `apidog export --help` die `--scope`, `--api-ids` und `--folder-ids` Flags zum Eingrenzen der Ausgabe. Ein einzelnes Projekt kann auf diese Weise eine Dokumentationsdatei pro Dienst versenden.

Ein vollständiges Beispiel, Ende zu Ende

Hier ist der gesamte Ablauf als eine Anfrage in einfacher Sprache und die Befehle, die ein Agent ausführt, um sie zu erfüllen.

Sie: „Wir haben gerade einen Zahlungsdienst mit `POST /refunds` und `GET /refunds/{id}` hinzugefügt. Dokumentieren Sie beides, schreiben Sie eine kurze Anleitung zur Erklärung von Idempotenzschlüsseln und veröffentlichen Sie diese auf unserer Dokumentationsseite.“

Der Agent, seinen Regeln folgend, führt aus:

# Das gemeinsame Datenmodell erstellen
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Beide Endpunkte erstellen
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Die Idempotenz-Anleitung als Markdown-Dokument verfassen
apidog doc create --project $PID --file ./idempotency-guide.json

# Veröffentlichen
apidog docs-site create --project $PID --file ./docs-site.json

Sie überprüfen den resultierenden Diff, und der Zahlungsdienst ist dokumentiert und live. Was früher ein Nachmittag des Kontextwechsels war, ist jetzt eine Anfrage und eine Überprüfung.

In einen Agenten-Loop oder CI einbinden

Da jeder Schritt ein Befehl ist, lässt sich der gesamte Workflow in CI oder in den Task-Loop eines Agenten integrieren. Ein minimaler Schritt, der Ihre Markdown-Referenz bei jedem Push neu generiert und committed:

- name: API-Dokumente neu generieren
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

Für ein umfassenderes Bild der End-to-End-Ausführung eines Agenten mit der CLI, siehe Vom PRD zum Test-Loop und Wie man 5 KI-Agenten einrichtet, um eine komplette API zu erstellen. Das Muster ist in beiden dasselbe wie hier: Absicht beschreiben, den Agenten in validierte CLI-Aufrufe übersetzen lassen, das Ergebnis überprüfen.

Ein Hinweis zu Berechtigungen

Das Schreiben in ein Projekt über einen Agenten kann gesperrt sein. Wenn ein `create`-Befehl als blockiert zurückkommt, wurden die externen KI-Bearbeitungsberechtigungen für diesen Branch im Projekt deaktiviert. Sie haben zwei ehrliche Optionen: Aktivieren Sie die direkte Bearbeitungsberechtigung in den Projekteinstellungen → Funktionsmerkmale → KI-Funktionsmerkmale (Apidog Client 2.8.32+), oder lassen Sie den Agenten in einem isolierten KI-Branch arbeiten und einen Merge-Request öffnen. Der Begleitführer zur Aktualisierung Ihrer API-Spezifikation beschreibt den vollständigen AI-Branch-Fluss und gilt gleichermaßen, wenn der Agent Dokumentation auf einem geschützten Branch erstellt.

Häufige Fallstricke

Der Agent hat die JSON von Hand erstellt. Dies ist der häufigste Fehler. Erzwingen Sie `cli-schema get` → `cli-schema validate` → `create` in den Anweisungen des Agenten, damit er mit dem echten Schema arbeitet, nicht mit einem geratenen.

Fehlende Projekt-ID. Jeder `doc`-, `docs-site`- und `export`-Aufruf benötigt `--project <projectId>`, die ID aus den Einstellungen, nicht den lesbaren Projektnamen. Die meisten "es gab einen Fehler"-Meldungen sind dies.

Verwechslung von `doc`, `docs-site` und `shared-doc`. Es sind drei verschiedene Dinge: eine Markdown-Seite im Baum, eine gehostete Seite und ein Freigabelink. Lassen Sie den Agenten bestätigen, was die Aufgabe bedeutet, bevor er schreibt.

Token in CI nicht gesetzt. `apidog login` speichert das Token auf der Maschine, die es ausführt. Ein frischer CI-Runner hat keins, also führen Sie `login --with-token` im selben Job vor jedem Befehl aus und bewahren Sie das Token in einem Secret auf.

Ein `$ref`, der ins Leere zeigt. Wenn ein Endpunkt ein Datenmodell mit `#/definitions/{schemaId}` referenziert, muss dieses Schema zuerst existieren. Erstellen Sie Schemas, bevor die Endpunkte, die sie verwenden.

FAQ

Welche KI-Agenten können die Apidog CLI steuern? Jeder Agent, der Shell-Befehle ausführen kann: Claude Code, Cursor, Codex und ähnliche Coding-Agenten. Die CLI ist agentenunabhängig; sie benötigt nur korrekte Befehle und gültige Payloads.

Brauche ich einen kostenpflichtigen Plan? Nein. Apidog ist nicht Open Source, aber der kostenlose Tarif plus `apidog-cli` deckt den hier beschriebenen Erstellungs- und Veröffentlichungsfluss ab.

Kann der Agent versehentlich bestehende Dokumente überschreiben? `create` fügt neue Ressourcen hinzu. Das Ändern bestehender verwendet `update`, was sich anders verhält und eigene Schutzvorkehrungen benötigt; dies wird im Begleitführer zur Aktualisierung Ihrer API-Spezifikation behandelt.

Wie unterscheidet sich dies von einem KI-Dokumentationsgenerator? Generische KI-Dokumentations-Tools erstellen Text aus Ihrem Code. Dies erstellt strukturierte Dokumentation innerhalb Ihrer API-Plattform (Endpunkte, Schemas, Anleitungen und eine veröffentlichte Website) aus einer einzigen Live-Quelle, die nicht von dem abweichen kann, was Ihr Team bearbeitet.

Zusammenfassung

Ein Agent, der die Apidog CLI ausführen kann, kann den Teil der Dokumentation übernehmen, den die Leute immer aufschieben: Er erstellt die Endpunkte, schreibt die Anleitungen dazu und veröffentlicht die Website. Alles auf Basis einer Anfrage in einfacher Sprache, mit Schema-Validierung, die jeden Schreibvorgang schützt. Ihre Rolle verschiebt sich vom Schreiben von Dokumenten zur Überprüfung eines Diffs.

Die eine Regel, die es zuverlässig macht, ist das Schreibritual: Schema abrufen, validieren, dann erstellen. Geben Sie Ihrem Agenten diese Schleife, den obigen Fünf-Zeilen-Regelblock und eine Projekt-ID, und die Dokumentation wird aufhören, eine lästige Pflicht zu sein, die dem Code hinterherhinkt. Laden Sie Apidog herunter, um die CLI zu erhalten, oder lesen Sie den vollständigen Apidog CLI-Leitfaden für die vollständige Befehlsreferenz.