Die API-Dokumentation ist wichtig, wird aber oft zu spät aktualisiert: Ein neuer Endpunkt ist live, die Referenz folgt Tage später, und der Quickstart beschreibt einen Authentifizierungsfluss, der längst ersetzt wurde. Genau diese wiederkehrende, leicht verschiebbare Arbeit eignet sich für einen KI-Agenten. Kann der Agent Terminalbefehle ausführen, kann er Endpunkte anlegen, Anleitungen schreiben und eine Dokumentationsseite veröffentlichen. Die Apidog CLI stellt dafür skriptfähige Befehle mit strukturierter JSON-Ausgabe bereit.
Apidog noch heute ausprobieren
Warum CLI statt GUI oder MCP-Server?
Ein Agent kann Ihre API-Dokumentation auf drei Arten beeinflussen. Diese Ansätze lösen unterschiedliche Aufgaben:
| Ansatz | Richtung | Steuerung | Überprüfbarer Diff? |
|---|---|---|---|
| GUI | Manuelle Bearbeitung im Browser | Mensch klickt | Nein |
| MCP-Server | Liest Spezifikation → schreibt Code | Agent im Editor | Im Code-Repo, nicht in den Docs |
| CLI | Schreibt Dokumentation direkt | Agent im Terminal | Ja, Befehle sind protokollierbar |
Ein MCP-Server ist sinnvoll, wenn ein Agent Ihre API-Definition lesen und daraus Client-Code generieren soll. Der Cursor-Doc-through-MCP-Flow ist ein typisches Beispiel.
Für diesen Workflow ist die CLI passender: Der Agent soll die Dokumentation selbst produzieren — Endpunkte, Markdown-Anleitungen und eine veröffentlichte Docs-Seite.
Die CLI bietet dabei drei praktische Vorteile:
- Deterministisch: Derselbe Befehl liefert dasselbe Ergebnis.
- Skriptfähig: Der Workflow lässt sich in Agent-Loops und CI integrieren.
-
Agentenfreundlich: JSON-Antworten enthalten
agentHints.nextSteps, sodass der Agent Folgebefehle aus der CLI-Ausgabe ableiten kann.
Die Agent-Umgebung einrichten
Installieren Sie die CLI und authentifizieren Sie sich einmalig:
npm install -g apidog-cli
apidog login --with-token <TOKEN>
Der Installationsleitfaden erklärt Node-Versionen und PATH-Konfiguration. Details zu Tokens und CI-Secrets finden Sie im Authentifizierungsleitfaden.
Den Token finden Sie in der Apidog-App unter Benutzeravatar → Kontoeinstellungen → API-Zugriffstoken. Nach dem Login wird er lokal gespeichert, sodass der Agent ihn nicht bei jedem Aufruf übergeben muss.
Jeder Schreibvorgang benötigt eine Projekt-ID. Sie finden sie unter Projekteinstellungen → Basiseinstellungen oder über:
apidog project list
Jeder Coding-Agent mit Shell-Zugriff kann diesen Flow ausführen, etwa Claude Code, Cursor, Codex oder vergleichbare Tools.
Das Schreibritual für Agents
Schreibbefehle erwarten JSON-Dateien. Lassen Sie den Agenten diese Payloads niemals frei erfinden. Falsche oder halluzinierte Feldnamen sind eine häufige Ursache für fehlgeschlagene Ausführungen.
Verwenden Sie stattdessen immer diesen Ablauf:
# 1. Das erwartete Payload-Schema abrufen
apidog cli-schema get doc-create
# 2. JSON-Datei anhand des Schemas erzeugen
# 3. Vor dem Schreiben lokal validieren
apidog cli-schema validate doc-create --file ./doc.json
# 4. Erst danach die Ressource erstellen
apidog doc create --project <projectId> --file ./doc.json
Fügen Sie diese Regeln in den System-Prompt des Agenten oder in eine CLAUDE.md- bzw. .cursorrules-Datei ein:
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 die Payload.
- 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 einen Menschen; verwenden Sie keinen Workaround.
Damit wird aus „Das Modell hat ein Feld erfunden“ ein lokal abgefangener Validierungsfehler.
Schritt 1: API-Referenz aus Endpunkten und Schemas erstellen
In Apidog wird die API-Referenz aus Endpunkten und Datenschemas im Projekt erzeugt. Der Agent erstellt daher zuerst wiederverwendbare Datenmodelle und anschließend die Endpunkte, die darauf verweisen.
Beispielanforderung:
„Fügen Sie einen
POST /refunds-Endpunkt hinzu, der eine Bestell-ID und einen Betrag entgegennimmt, und dokumentieren Sie Erfolgs- und Validierungsfehler-Antworten.“
Zuerst erstellt der Agent ein Schema für Rückerstattungen. Das Schema schema-create zeigt, dass mindestens name und jsonSchema benötigt werden.
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
Danach folgt der Endpunkt. endpoint-create verlangt unter anderem method und path. Das zuvor erstellte Schema kann über $ref eingebunden werden.
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
Sobald der Endpunkt angelegt ist, steht die Referenz im Projekt bereit. Es ist kein separater Export-Schritt nötig: Die Referenz wird aus derselben Definition gerendert, die Ihr Team pflegt.
Schritt 2: Markdown-Anleitungen erstellen
Eine API-Referenz reicht selten aus. Entwickler benötigen zusätzlich Quickstarts, Authentifizierungsanleitungen, Migrationshinweise und Erklärungen zu wiederkehrenden Konzepten.
In Apidog liegen diese Inhalte als Markdown-Dokumente im Docs-Baum des Projekts und werden mit der Befehlsgruppe doc verwaltet.
Das Schema doc-create benötigt mindestens name. Der Markdown-Inhalt kommt in content; folderId definiert die Position im Baum. 0 steht für das Stammverzeichnis.
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
Praktischer Agenten-Prompt:
„Schreibe einen Schnellstart, der einen neuen Entwickler vom API-Schlüssel bis zur ersten Rückerstattung führt.“
Der Agent kann daraus Markdown erstellen, es in eine gültige Payload verpacken, lokal validieren und anschließend veröffentlichen — ohne Browser und ohne manuelles Kopieren.
Schritt 3: Docs-Seite veröffentlichen
Für die Veröffentlichung sind drei Begriffe wichtig:
-
doc: Ein Markdown-Dokument innerhalb des API-Baums. -
docs-site: Eine gehostete, öffentliche Dokumentationsseite. -
shared-doc: Ein teilbarer Link, aber keine vollständige Docs-Website.
Beispiel für eine Docs-Site:
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 der Agent eine öffentliche Dokumentationsseite konfigurieren oder veröffentlichen soll. Verwenden Sie shared-doc, wenn lediglich ein Link für Partner oder Tester benötigt wird.
Da auch die Veröffentlichung ein CLI-Schritt ist, kann sie direkt nach Änderungen an Endpunkten oder Markdown-Dokumenten ausgeführt werden.
Schritt 4: Portable Dokumentation exportieren
Für statische Websites, externe Hosting-Plattformen oder nachgelagerte Systeme können Sie die Dokumentation exportieren:
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 ein Projekt mehrere Dienste enthält, zeigt apidog export --help Optionen wie --scope, --api-ids und --folder-ids, um den Export einzugrenzen.
Vollständiges Beispiel: Von der Anfrage zur veröffentlichten Dokumentation
Anforderung:
Sie: „Wir haben gerade einen Zahlungsdienst mit
POST /refundsundGET /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 folgt dem Schema- und Validierungsablauf:
# Gemeinsames 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
# Idempotenz-Anleitung als Markdown-Dokument erstellen
apidog doc create --project $PID --file ./idempotency-guide.json
# Docs-Site veröffentlichen
apidog docs-site create --project $PID --file ./docs-site.json
Danach prüfen Sie den resultierenden Diff. Der Zahlungsdienst ist dokumentiert und veröffentlicht.
In Agent-Loops und CI integrieren
Da jeder Schritt per Befehl ausführbar ist, lässt sich der Ablauf in CI oder in den Task-Loop eines Agenten integrieren.
Ein minimaler CI-Schritt, der eine Markdown-Referenz bei jedem Push erzeugt:
- 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
Weitere Beispiele für agentengesteuerte CLI-Workflows finden Sie in Vom PRD zum Test-Loop und Wie man 5 KI-Agenten einrichtet, um eine komplette API zu erstellen.
Das Muster bleibt gleich:
- Absicht beschreiben.
- Agent in validierte CLI-Aufrufe übersetzen lassen.
- Ergebnis und Diff überprüfen.
Berechtigungen beachten
Schreibzugriffe können für einen Branch gesperrt sein. Wenn ein create-Befehl blockiert zurückkommt, sind externe KI-Bearbeitungsberechtigungen für diesen Branch deaktiviert.
Es gibt zwei saubere Optionen:
- Direkte Bearbeitungsberechtigung aktivieren: Projekteinstellungen → Funktionsmerkmale → KI-Funktionsmerkmale in Apidog Client 2.8.32+.
- Den Agenten in einem isolierten KI-Branch arbeiten lassen und anschließend einen Merge-Request erstellen lassen.
Der Leitfaden zum Aktualisieren einer API-Spezifikation per Agent beschreibt den vollständigen AI-Branch-Flow. Das gilt ebenso für Dokumentation auf geschützten Branches.
Häufige Fallstricke
Der Agent erstellt JSON-Payloads frei aus dem Gedächtnis.
Erzwingen Sie die Reihenfolge cli-schema get → cli-schema validate → create. So arbeitet der Agent mit dem tatsächlichen CLI-Schema.
Die Projekt-ID fehlt.
Jeder doc-, docs-site- und export-Befehl benötigt --project <projectId>. Verwenden Sie die ID aus den Projekteinstellungen, nicht den lesbaren Projektnamen.
doc, docs-site und shared-doc werden verwechselt.
doc erstellt eine Markdown-Seite im Docs-Baum. docs-site betrifft die gehostete Website. shared-doc erzeugt einen Freigabelink.
Das Token fehlt in CI.
apidog login speichert Tokens nur auf dem Rechner, auf dem der Befehl ausgeführt wird. Ein frischer CI-Runner benötigt daher in jedem Job erneut login --with-token.
Ein $ref verweist auf kein existierendes Schema.
Wenn ein Endpunkt #/definitions/{schemaId} verwendet, muss das Schema zuerst angelegt werden. Erstellen Sie immer erst die Datenmodelle, dann die Endpunkte.
FAQ
Welche KI-Agenten können die Apidog CLI steuern?
Jeder Agent mit Shell-Zugriff, beispielsweise Claude Code, Cursor, Codex oder ähnliche Coding-Agenten. Die CLI ist agentenunabhängig und erwartet nur korrekte Befehle sowie 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öffentlichungsflow ab.
Kann ein Agent bestehende Dokumente überschreiben?
create fügt neue Ressourcen hinzu. Für Änderungen an bestehenden Ressourcen wird update verwendet. Dafür gelten eigene Schutzvorkehrungen, die im Leitfaden zur Aktualisierung von API-Spezifikationen beschrieben sind.
Wie unterscheidet sich das von einem generischen KI-Dokumentationsgenerator?
Generische Tools erzeugen meist Text aus Code. Dieser Workflow erstellt strukturierte Dokumentation direkt in der API-Plattform: Endpunkte, Schemas, Markdown-Anleitungen und eine veröffentlichte Website. Die Referenz basiert auf derselben Quelle, die Ihr Team bearbeitet.
Zusammenfassung
Ein Agent mit Zugriff auf die Apidog CLI kann die Dokumentationsarbeit übernehmen, die sonst oft liegen bleibt: Endpunkte anlegen, Anleitungen schreiben und die Docs-Seite veröffentlichen.
Der entscheidende Ablauf lautet:
Schema abrufen → Payload erstellen → validieren → schreiben
Geben Sie Ihrem Agenten diese Schleife, die CLI-Regeln und eine Projekt-ID. Dann verschiebt sich Ihre Aufgabe vom manuellen Schreiben zur Überprüfung eines nachvollziehbaren Diffs.
Laden Sie Apidog herunter, um die CLI zu verwenden, oder lesen Sie den vollständigen Apidog CLI-Leitfaden.
Top comments (0)