DEV Community

Cover image for Apidog CLI: API-Spezifikation mit KI-Agenten automatisch aktualisieren
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Apidog CLI: API-Spezifikation mit KI-Agenten automatisch aktualisieren

Das manuelle Aktualisieren einer API-Spezifikation ist fehleranfällig: Ein Feld umbenennen, einen Enum-Wert ergänzen oder ein Feld verpflichtend machen klingt klein, kann aber abhängige Endpunkte beschädigen. Mit der Apidog-CLI können Sie diese Änderungen durch einen KI-Agenten ausführen lassen – mit Schema-Validierung, isoliertem Branch und prüfbarem Merge-Request.

Apidog heute testen

Die CLI ergänzt den Workflow zum Erstellen von API-Dokumentationen durch einen Agenten. Dokumentation zu erzeugen ist additiv und meist risikoarm. Einen bestehenden API-Vertrag zu ändern, benötigt dagegen klare Schutzmechanismen.

Was „Spezifikation aktualisieren“ in der CLI bedeutet

Eine Apidog-Spezifikation umfasst Endpunkte und Datenschemas eines Projekts. Für Änderungen verwenden Sie typischerweise einen dieser Befehle:

  • endpoint update: Pfad, Parameter oder Antwort eines Endpunkts ändern.
  • schema update: Ein Datenmodell ändern, auf das Endpunkte verweisen.
  • import: Eine OpenAPI-Datei importieren und mit dem Projekt abgleichen.

Bevor ein Agent diese Befehle nutzt, müssen zwei Regeln gelten:

  1. update ersetzt Ressourcen vollständig.
  2. Änderungen gehören auf einen isolierten KI-Branch.

Wichtig: update ist kein Patch, sondern ein vollständiger Ersatz

Die update-Befehle verhalten sich nicht wie JSON Patch. Übergeben Sie nur einen Teil eines Arrays, etwa einen einzelnen Eintrag aus parameters, ersetzt die CLI das gesamte Array durch diesen Teil. Alle nicht gesendeten Werte gehen verloren.

Verwenden Sie daher immer Lesen → Ändern → Validieren → Schreiben mit dem vollständigen Objekt:

# 1. Vollständige aktuelle Ressource abrufen
apidog endpoint get <endpointId> --project <projectId>

# 2. Vollständige Struktur lokal bearbeiten.
#    Nicht geänderte Felder beibehalten.

# 3. Vollständiges Objekt gegen das CLI-Schema validieren
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Vollständiges Objekt zurückschreiben
apidog endpoint update <endpointId> --project <projectId> \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Geben Sie einem Agenten diese Regel explizit:

Sende niemals ein partielles Objekt an update. Rufe immer die vollständige Ressource ab, ändere sie lokal und schreibe das vollständige Objekt zurück.

Damit vermeiden Sie stille Datenverluste. Die Validierung mit cli-schema validate fängt außerdem ungültige Nutzlasten ab, bevor sie das Projekt erreichen.

Sicherer Workflow: Änderungen auf einem KI-Branch ausführen

Geben Sie einem Agenten nicht direkt Schreibrechte auf main, insbesondere nicht zu Beginn. Nutzen Sie stattdessen einen KI-Branch:

  • Der Agent bearbeitet Ressourcen isoliert.
  • Der Quell-Branch bleibt unverändert.
  • Erst nach Ihrer Prüfung wird gemergt.
  • Unerwünschte Änderungen lassen sich durch Archivieren des Branches verwerfen.

Das entspricht praktisch einem Pull-Request-Workflow für Ihre API-Spezifikation.

Schritt 1: KI-Branch erstellen 

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie eine eindeutige Namenskonvention, zum Beispiel:

ai/JJJJMMTT-von-Quelle-feature
Enter fullscreen mode Exit fullscreen mode

So erkennen Sie Quelle und Zweck des Branches sofort. Der Wert für --from muss main oder ein normaler Sprint-Branch sein, kein allgemeiner Branch.

Ein KI-Branch ohne Unterschiede zur Quelle wird nach 24 Stunden automatisch archiviert.

Schritt 2: Bestehende Ressourcen in den KI-Branch übernehmen

Ein KI-Branch startet leer und klont den Quell-Branch nicht automatisch. Soll der Agent einen vorhandenen Endpunkt oder ein bestehendes Schema ändern, müssen Sie die Ressource zuerst mit pick-to in den Branch übernehmen:

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Dieser Schritt ist nur für bestehende Ressourcen nötig. Ressourcen, die der Agent neu im KI-Branch erstellt, müssen nicht übernommen werden.

Schritt 3: Agent im KI-Branch arbeiten lassen

Der Agent führt nun dieselbe Lesen-Ändern-Schreiben-Schleife aus, ergänzt aber --branch:

# Vollständigen Endpunkt aus dem KI-Branch abrufen
apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

# Vollständigen, validierten Endpunkt zurückschreiben
apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

main bleibt dabei unverändert. Fehler bleiben auf dem isolierten Branch.

Schritt 4: Diff prüfen und zusammenführen

KI-Branches werden nicht automatisch zurückgemergt. Prüfen Sie den Diff, bevor die Änderung in main landet.

Ist das Ziel geschützt, verwenden Sie einen Merge-Request statt eines direkten Merges:

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Ein direkter Merge benötigt Direktbearbeitungsberechtigungen für Quell- und Ziel-Branch. Ist main geschützt, bevorzugen Sie merge-request und genehmigen Sie die Änderung im Apidog-Client.

Praxisbeispiel: amount sicher in amountCents umbenennen

Angenommen, das Datenmodell Refund enthält das Feld amount. Sie möchten es in amountCents umbenennen und auf Ganzzahlwerte umstellen.

Die Agenten-Anweisung lautet:

Benenne das Feld amount im Refund-Schema in amountCents um und ändere seinen Typ zu integer.

Zuerst liest der Agent das vollständige Schema im KI-Branch:

apidog schema get <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Anschließend bearbeitet er das vollständige jsonSchema. Alle unveränderten Felder bleiben erhalten:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Wichtig: Der Agent sendet nicht nur amountCents, sondern das gesamte Schema inklusive orderId und reason.

Danach validiert und schreibt er das vollständige Objekt zurück:

# Vollständiges Schema validieren
apidog cli-schema validate schema-create --file ./refund-full.json

# Änderung in den KI-Branch schreiben
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie anschließend den Diff: Ein Feld wurde umbenannt, andere Eigenschaften wurden nicht verändert. Erst dann mergen Sie den Branch.

Breaking Changes vor dem Merge stoppen

Das Umbenennen eines Pflichtfelds ist eine Breaking Change. Clients, die weiterhin amount senden, bestehen die Validierung nicht mehr.

Ergänzen Sie die Agentenregeln um eine verpflichtende Klassifizierung:

Vor dem Zusammenführen einer Spezifikationsänderung klassifiziere sie:

- Nicht-Breaking:
  neues optionales Feld, neuer Endpunkt, gelockerte Einschränkung
  → Änderung zusammenfassen und mit dem Merge-Request fortfahren.

- Breaking:
  umbenanntes oder entferntes Feld, neues Pflichtfeld, verschärfter Typ
  → STOPP.
  Breaking Change und betroffene Endpunkte melden.
  Auf explizite menschliche Genehmigung warten.
Enter fullscreen mode Exit fullscreen mode

Der KI-Branch macht diesen Kontrollpunkt wirksam: Ohne Merge gelangt die Änderung nicht nach main.

Stattdessen eine OpenAPI-Datei importieren

Liegt die Änderung bereits als OpenAPI-Datei vor, können Sie sie importieren, statt Felder einzeln zu aktualisieren:

apidog import --project <projectId> --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

import akzeptiert unter anderem OpenAPI 3.x, Swagger 2.0 und Postman. Führen Sie den Import zuerst im KI-Branch aus und prüfen Sie den Diff, bevor Sie Änderungen nach main übernehmen.

Nach dem Merge können Sie die abgeglichene Spezifikation exportieren und überprüfen:

apidog export --project <projectId> --format openapi \
  --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Dieser Weg eignet sich, wenn die Quelle der Wahrheit außerhalb von Apidog liegt. Für gezielte Änderungen an einer in Apidog gepflegten Spezifikation ist update mit vollständigem Objekt die bessere Wahl.

Fehler rückgängig machen: Branch archivieren

Wenn der Agent eine unerwünschte Änderung erstellt, wurde main nicht verändert. Archivieren Sie einfach den KI-Branch:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> --type ai
Enter fullscreen mode Exit fullscreen mode

Ein KI-Branch ohne akzeptierte Differenz wird ohnehin nach 24 Stunden automatisch archiviert. Der Branch ist damit kein unnötiger Prozessschritt, sondern Ihr Rückgängig-Button.

Berechtigungen beachten

Wenn update oder import blockiert wird, sind möglicherweise die externen KI-Bearbeitungsberechtigungen des Projekts deaktiviert.

Der KI-Branch-Workflow ist dafür vorgesehen:

  1. Agent bearbeitet einen isolierten Branch.
  2. Mensch prüft die Änderung.
  3. Mensch genehmigt den Merge.

Falls direkte Bearbeitungen gewünscht sind, finden Sie die Einstellung unter:

Projekteinstellungen → Feature-Einstellungen → KI-Feature-Einstellungen
Enter fullscreen mode Exit fullscreen mode

Diese Einstellung ist im Apidog Client ab Version 2.8.32 verfügbar. Trifft ein Agent auf eine Berechtigungssperre, sollte er nicht eigenständig einen Workaround wählen, sondern die Entscheidung an einen Menschen eskalieren.

Häufige Fallstricke

Partielle Aktualisierung löscht Felder

update ersetzt statt zusammenzuführen. Immer vollständige Ressource abrufen, vollständig bearbeiten, validieren und zurückschreiben.

Bestehende Ressource im KI-Branch ohne pick-to bearbeiten

KI-Branches starten leer. Übernehmen Sie vorhandene Endpunkte oder Schemas zuerst mit pick-to.

Falscher --from-Branch

Ein KI-Branch muss von main oder einem Sprint-Branch stammen, nicht von einem allgemeinen Branch.

Validierung überspringen

cli-schema validate erkennt ungültige Nutzlasten lokal. Ohne Validierung wird aus einem Tippfehler schnell ein fehlgeschlagener API-Aufruf oder ein fehlerhafter Merge.

Breaking Changes stillschweigend mergen

Machen Sie die Klassifizierung jeder Änderung zu einem expliziten Agenten-Schritt. Breaking Changes müssen menschlich genehmigt werden.

FAQ

Kann ein Agent main direkt bearbeiten?

Ja, wenn externe KI-Bearbeitungsberechtigungen aktiviert sind. Ein KI-Branch ist aber sicherer, weil keine Änderung ohne genehmigten Merge nach main gelangt.

Was ist der Unterschied zwischen branch merge und merge-request?

branch merge schreibt Änderungen direkt und benötigt Direktbearbeitungsberechtigungen für beide Branches. merge-request erstellt eine überprüfbare Anfrage und ist die bessere Wahl für geschützte Main-Branches.

Benötigt der Agent die Apidog-Desktop-App?

Nein. Die CLI ist eigenständig. Die App wird nur benötigt, um externe KI-Bearbeitungsberechtigungen einmalig zu konfigurieren.

Wie verhindere ich halluzinierte Feldnamen?

Nutzen Sie die Schleife cli-schema get → validate. Eine Nutzlast mit einem nicht existierenden oder ungültigen Feld schlägt bei der lokalen Validierung fehl, bevor sie das Projekt verändert.

Zusammenfassung

Eine KI kann API-Spezifikationen sicher aktualisieren, wenn drei Regeln gelten:

  1. Änderungen erfolgen auf einem isolierten KI-Branch.
  2. Jede Aktualisierung folgt dem Muster Lesen → Ändern → Validieren → vollständiges Schreiben.
  3. Ein Mensch prüft und genehmigt den Merge, insbesondere bei Breaking Changes.

Mit der Apidog-CLI lässt sich dieser Ablauf skripten und prüfen. Eine schlechte Änderung bleibt auf dem KI-Branch und lässt sich mit archive verwerfen.

Laden Sie Apidog herunter, um die CLI zu verwenden, und kombinieren Sie den Workflow mit dem Erstellen von API-Dokumentationen durch einen Agenten.

Top comments (0)