Das manuelle Bearbeiten einer API-Spezifikation ist eine mühsame Arbeit. Ein Feld umbenennen, einen Enum-Wert hinzufügen, ein Pflicht-Flag verschärfen. Jede Änderung ist klein, aber jede muss an der richtigen Stelle landen, ohne die Endpunkte zu beschädigen, die darauf verweisen. Es ist präzise, mechanisch und genau die Art von Aufgabe, die man einem KI-Agenten überlassen würde – wenn man ihm nur vertrauen könnte, dass er nicht das gesamte Schema zunichtemacht.
Sie können das. Die Apidog CLI gibt einem Agenten alles, was er braucht, um eine Spezifikation verantwortungsvoll zu ändern: Schema-Validierung vor jedem Schreibvorgang, einen isolierten Branch, an dem gearbeitet werden kann, und einen Merge-Request zur Überprüfung.
Dies ist die Mutations-Ergänzung dazu, einem Agenten das Erstellen von API-Dokumentationen zu ermöglichen. Das Erstellen ist additiv und risikoarm; das Aktualisieren eines bestehenden Vertrags ist der Punkt, an dem Schutzmechanismen wichtig sind, daher geht es in diesem Leitfaden hauptsächlich darum, dies ohne Beschädigungen zu tun.
Was „die Spezifikation aktualisieren“ in der CLI bedeutet
Ihre Spezifikation in Apidog ist die Menge der Endpunkte und Datenschemata in einem Projekt. Sie zu aktualisieren bedeutet einen von drei Befehlen:
endpoint update: Ändern Sie einen Pfad, einen Parameter, eine Antwort.schema update: Ändern Sie ein Datenmodell, auf das Endpunkte verweisen.import: Bringen Sie eine ganz neue OpenAPI-Datei ein, um sie mit dem Projekt abzugleichen.
Bevor Sie einen Agenten auf einen dieser Befehle ansetzen, müssen Sie zwei Verhaltensweisen verstehen, denn ein falscher Umgang damit kann zu einer Beschädigung der Spezifikation führen. Das erste ist ein Berechtigungsmodell, und das zweite ist eine Tücke, die still und leise Daten löscht.
Die Tücke, die Ihnen auf die Füße fallen wird: „update“ ist ein vollständiger Ersatz
Dies ist das Wichtigste, was Sie Ihrem Agenten beibringen müssen. Die update-Befehle der CLI sind kein JSON Patch. Sie übermitteln die von Ihnen angegebenen Felder direkt; sie führen keine Array-Elemente nach ID zusammen. Wenn Sie ein Update mit einem teilweisen parameters-Array senden, um einen Parameter zu ändern, bearbeiten Sie diesen Parameter nicht. Sie ersetzen das gesamte Array durch genau das eine, das Sie gesendet haben, und der Rest ist verschwunden.
Die korrekte Reihenfolge ist immer Lesen-Ändern-Schreiben am vollständigen Objekt:
# 1. Das vollständige aktuelle Ressource abrufen
apidog endpoint get <endpointId> --project <projectId>
# 2. Die vollständige Struktur lokal bearbeiten (alle Felder beibehalten, die Sie nicht ändern)
# 3. Das gesamte Objekt gegen das Schema validieren
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Das vollständige Objekt zurückschreiben
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Geben Sie dies dem Agenten in einfachen Worten als Anweisung: Senden Sie niemals ein partielles Objekt an update; rufen Sie immer die vollständige Ressource ab, ändern Sie sie und senden Sie sie ganz zurück. Ein Agent, der den get-Schritt überspringt, wird still und leise Felder verwerfen. Ein Agent, der zuerst cli-schema validate ausführt, fängt seine eigenen Fehler ab, bevor sie das Projekt erreichen.
Der sichere Weg: Lassen Sie den Agenten an einem KI-Branch arbeiten
Sie könnten dem Agenten die direkte Bearbeitungsberechtigung für Ihren Haupt-Branch erteilen. Tun Sie das nicht, zumindest nicht zu Beginn. Apidog verfügt über einen speziell entwickelten Isolationsmechanismus, den KI-Branch, der genau dafür konzipiert ist: Ein Agent ändert Ressourcen, ohne den Quell-Branch zu berühren, und nichts wird zurückgemergt, bis Sie es sagen. Stellen Sie es sich wie einen Pull-Request für Ihre API-Spezifikation vor.
Schritt 1: Den KI-Branch erstellen
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
Die Namenskonvention ist ai/JJJJMMTT-von-Quelle-Feature, sodass Ursprung und Zweck des Branches auf einen Blick ersichtlich sind. Der --from-Wert muss Ihr Haupt-Branch oder ein normaler Sprint-Branch sein, kein allgemeiner Branch. Ein praktisches Detail: Ein KI-Branch ohne Unterschied zu seiner Quelle wird nach 24 Stunden automatisch archiviert, sodass verlassene Experimente sich selbst bereinigen.
Schritt 2: Die Ressourcen importieren, die der Agent bearbeiten wird
Ein KI-Branch beginnt leer. Er klont den Quell-Branch nicht automatisch. Bevor der Agent einen bestehenden Endpunkt oder ein Schema bearbeiten kann, ziehen Sie diese Ressource mit pick-to in den Branch:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Ressourcen, die der Agent frisch auf dem Branch erstellt, benötigen dies nicht; nur bestehende, die er ändern oder löschen möchte. Dies ist der Schritt, den die Leute vergessen: Überspringen Sie ihn, und der Agent hat einen leeren Branch und nichts zu bearbeiten.
Schritt 3: Lassen Sie den Agenten die Änderung vornehmen
Nun führt der Agent die Schleife Lesen-Ändern-Schreiben von zuvor aus, aber mit --branch, das auf den KI-Branch verweist. Jede Bearbeitung ist eingedämmt:
apidog endpoint get <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields"
apidog endpoint update <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields" \
--file ./endpoint-full.json
Ihr Haupt-Branch bleibt die ganze Zeit unberührt. Wenn der Agent etwas falsch macht, beschränkt sich der Auswirkungsbereich auf einen Wegwerf-Branch.
Schritt 4: Überprüfen, dann zusammenführen
Änderungen an KI-Branches werden niemals automatisch zurückgeschrieben. Wenn der Agent fertig ist, entscheiden Sie, was passiert. Wenn das Ziel geschützt ist, öffnen Sie einen Merge-Request, anstatt direkt zusammenzuführen:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Überprüfen Sie den Diff, genehmigen Sie ihn, und die geprüfte Änderung landet auf main. Ein direkter Merge über die CLI erfordert Direktbearbeitungsberechtigungen für sowohl den Quell- als auch den Ziel-Branch; wenn der Main-Branch geschützt ist, bevorzugen Sie merge-request und genehmigen Sie ihn im Apidog-Client.
Ein Arbeitsbeispiel: Ein Feld sicher umbenennen
Abstrakte Regeln sind leicht zuzustimmen und schwer anzuwenden. Hier ist ein konkretes Beispiel. Angenommen, Sie möchten amount auf dem Refund-Datenmodell in amountCents umbenennen, weil Sie zu ganzzahligen Cent-Beträgen wechseln.
Sie sagen dem Agenten: „Benennen Sie das Feld amount im Refund-Schema in amountCents um und machen Sie es zu einem Integer.“ Gemäß seinen Regeln führt der Agent aus:
# 1. Das VOLLSTÄNDIGE aktuelle Schema auf dem KI-Branch abrufen
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Es erhält das vollständige Objekt zurück und bearbeitet das ganze jsonSchema, wobei alle Felder, die es nicht berührt, beibehalten werden:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Beachten Sie, was *nicht* passiert ist: Es wurde nicht nur die eine geänderte Eigenschaft gesendet. Es wurde das gesamte Schema mit orderId und reason intakt gesendet, da update ersetzt. Dann:
# 2. Das vollständige Objekt validieren
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Es zurück in den KI-Branch schreiben
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Sie überprüfen den KI-Branch-Diff (ein Feld umbenannt, nichts anderes gestört) und führen ihn zusammen. Das ist die ganze Disziplin: vollständiges Objekt, validiert, auf einem Branch, nach Überprüfung zusammengeführt.
Breaking Changes kennzeichnen, bevor Sie zusammenführen
Das Umbenennen eines Pflichtfelds ist eine Breaking Change: Jeder Client, der amount sendet, wird nun die Validierung nicht bestehen. Ein guter Anweisungssatz für den Agenten veranlasst das Modell, dies zu sagen, anstatt stillschweigend zusammenzuführen. Fügen Sie dies den Regeln des Agenten hinzu:
Vor dem Zusammenführen einer Spezifikationsänderung, klassifizieren Sie sie:
- Nicht-Breaking (neues optionales Feld, neuer Endpunkt, gelockerte Einschränkung) → zusammenfassen und mit dem Merge-Request fortfahren.
- Breaking (umbenanntes/entferntes Feld, neues Pflichtfeld, verschärfter Typ) → STOPP.
Melden Sie den Breaking Change und die betroffenen Endpunkte und warten Sie auf eine explizite menschliche Genehmigung.
Der KI-Branch macht dies sicher durchsetzbar: Da nichts automatisch zusammengeführt wird, ist „Stopp und Bericht“ ein echter Kontrollpunkt, kein Wettlauf gegen einen bereits erfolgten Schreibvorgang.
Stattdessen von einer OpenAPI-Datei aktualisieren
Manchmal existiert die Änderung bereits als OpenAPI-Datei, aus Code generiert, anderswo bearbeitet oder von einem anderen Team übergeben. Anstatt Änderungen Feld für Feld zu wiederholen, kann der Agent die Datei importieren, um sie mit dem Projekt abzugleichen:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
import akzeptiert OpenAPI 3.x, Swagger 2.0, Postman und mehr. Führen Sie es zuerst gegen einen KI-Branch aus, damit Sie überprüfen können, was die eingehende Spezifikation ändert, bevor sie den Main-Branch erreicht. Exportieren Sie nach dem Mergen die abgeglichene Spezifikation erneut, um das Ergebnis zu bestätigen:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Dieser Weg ist am besten, wenn die Quelle der Wahrheit außerhalb von Apidog liegt und Sie sie synchronisieren. Der Feld-für-Feld-update-Weg ist am besten, wenn Apidog die Quelle der Wahrheit ist und Sie eine chirurgische Änderung vornehmen.
Wenn der Agent es falsch macht: Rollback
Der Grund, an einem KI-Branch zu arbeiten, ist, dass Fehler leicht rückgängig zu machen sind. Wenn der Agent eine Änderung vornimmt, die Sie nicht wünschen, haben Sie sie nie zusammengeführt, sodass der Main-Branch bereits korrekt ist. Archivieren Sie einfach den Branch und fahren Sie fort:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Da ein KI-Branch ohne akzeptierte Differenz ohnehin nach 24 Stunden automatisch archiviert wird, bereinigt sich sogar ein vergessenes Experiment von selbst. Vergleichen Sie das mit einem Agenten, der den Main-Branch direkt bearbeitet, wo ein schlechtes update sofort live ist und Ihr einziger Ausweg der Papierkorb oder eine manuelle Rückgängigmachung ist. Der Branch ist keine Bürokratie; er ist der Rückgängig-Button.
Ein Hinweis zu Berechtigungen
Wenn ein update oder import als blockiert zurückkommt, sind die externen KI-Bearbeitungsberechtigungen des Projekts deaktiviert. Das ist eine bewusste Sperre, und der oben beschriebene KI-Branch-Flow ist die Antwort darauf: Der Agent bearbeitet einen isolierten Branch, und Sie genehmigen den Merge. Wenn Sie lieber direkte Bearbeitungen zulassen möchten, befindet sich der Schalter in den Projekteinstellungen → Feature-Einstellungen → KI-Feature-Einstellungen (Apidog Client 2.8.32+). Wenn ein Agent auf eine Berechtigungswand stößt, lassen Sie ihn nicht stillschweigend einen Workaround wählen; legen Sie die Wahl einem Menschen vor.
Häufige Fallstricke
Partielle Aktualisierung löschte Felder. Der schädlichste und häufigste Fehler. update ersetzt; es führt nicht zusammen. Rufen Sie das vollständige Objekt ab, bearbeiten Sie es ganz, validieren Sie es, und schreiben Sie es dann. Wenn ein Feld verschwunden ist, hat der Agent eine partielle Nutzlast gesendet.
Bearbeiten einer bestehenden Ressource in einem KI-Branch ohne sie zu importieren. Der Branch beginnt leer. pick-to Sie die Ressource zuerst herein, sonst hat der Agent nichts zu bearbeiten.
Falsches --from für den KI-Branch. Die Quelle muss Main oder ein Sprint-Branch sein, niemals ein allgemeiner Branch. Der Befehl branch create wird sich beschweren, wenn Sie dies falsch machen.
Validierung überspringen. cli-schema validate fängt eine fehlerhafte Nutzlast auf Ihrem Rechner ab. Ein Agent, der ohne Validierung schreibt, verwandelt einen Tippfehler in einen fehlgeschlagenen API-Aufruf oder, schlimmer noch, einen schlechten Merge.
Einen Breaking Change stillschweigend zusammenführen. Ohne eine „zuerst klassifizieren“-Regel wird ein Agent gerne ein Pflichtfeld umbenennen und es zusammenführen. Machen Sie die Erkennung von Breaking Changes zu einem expliziten Kontrollpunkt.
FAQ
Kann ich dem Agenten erlauben, den Main-Branch direkt zu bearbeiten? Ja, indem Sie die externen KI-Bearbeitungsberechtigungen aktivieren, aber der Start auf einem KI-Branch ist sicherer: Nichts landet auf Main, bis Sie einen Merge genehmigen. Reservieren Sie direkte Bearbeitungen für risikoarme, hochvertrauenswürdige Automatisierungen.
Was ist der Unterschied zwischen branch merge und merge-request? branch merge schreibt die Änderung sofort durch und benötigt Direktbearbeitungsberechtigungen für beide Branches. merge-request öffnet eine überprüfbare Anfrage, die richtige Wahl, wenn Main geschützt ist.
Benötigt der Agent die Apidog Desktop-App? Nein, die CLI ist eigenständig. Die App ist nur für das Umschalten der Einstellung „Externe KI-Bearbeitungsberechtigungen“ wichtig, was eine einmalige Konfiguration ist.
Wie stelle ich sicher, dass der Agent keinen Feldnamen halluziniert? Die Schleife cli-schema get → validate ist die Leitplanke. Eine Nutzlast mit einem erfundenen Feld schlägt die Validierung lokal fehl, bevor sie überhaupt das Projekt erreicht.
Zusammenfassung
Einen Agenten Ihre API-Spezifikation aktualisieren zu lassen, ist sicher, wenn drei Dinge zutreffen: Er arbeitet an einem isolierten KI-Branch, er behandelt jede Aktualisierung als vollständiges Lesen-Ändern-Schreiben statt als Patch, und ein Mensch genehmigt den Merge. Die Apidog CLI bietet Ihnen alle drei als Befehle, was bedeutet, dass die gesamte Schleife (bearbeiten, validieren, überprüfen) skriptfähig und überprüfbar ist, und eine schlechte Änderung ist nur einen archive-Befehl von der Beseitigung entfernt.
Richten Sie den KI-Branch ein, geben Sie dem Agenten die Regel Lesen-Ändern-Schreiben und den Breaking-Change-Kontrollpunkt, und die Spezifikationswartung wird zu einem Diff, den Sie genehmigen, anstatt zu einer mühsamen Arbeit, die Sie ständig aufschieben. Laden Sie Apidog herunter, um die CLI zu erhalten, und kombinieren Sie dies mit dem Erstellen Ihrer Dokumente durch einen Agenten, um den gesamten Erstellungs- und Wartungszyklus abzudecken.