API仕様を手作業で編集するのは手間のかかる作業です。フィールド名の変更、列挙値の追加、必須フラグの厳格化。それぞれの変更は小さいですが、参照しているエンドポイントを壊すことなく、適切な場所に適用される必要があります。それは正確で機械的であり、AIエージェントに任せたい種類のタスクです。もしAIがスキーマ全体を破壊しないと信頼できるのであれば、の話ですが。
それが可能です。Apidog CLIは、エージェントが責任を持って仕様を変更するために必要なすべてを提供します。書き込み前のスキーマ検証、作業用分離ブランチ、そしてレビュー用のマージリクエストです。
これは、エージェントにAPIドキュメントを作成させることに対する、変更の補足です。作成は追加的でリスクが低いですが、既存の契約を更新する際にはガードレールが重要になるため、このガイドのほとんどは、何も壊さずにそれを行う方法について説明しています。
CLIにおける「仕様の更新」とは
Apidogにおける仕様とは、プロジェクト内のエンドポイントとデータスキーマの集合です。それを更新するということは、以下の3つのコマンドのいずれかを意味します。
endpoint update: パス、パラメータ、レスポンスを変更します。schema update: エンドポイントが参照するデータモデルを変更します。import: 新しいOpenAPIファイルをプロジェクトにインポートして調整します。
エージェントをこれらのいずれかに向けさせる前に、2つの振る舞いを理解しておく必要があります。これらを誤解すると、仕様が損なわれる原因となるからです。1つ目は権限モデル、2つ目はデータを密かに削除してしまう落とし穴です。
落とし穴：更新は完全な置き換えである
これはエージェントに教えるべき最も重要なことです。CLIのupdateコマンドはJSON Patchではありません。提供されたフィールドを直接送信します。IDによる配列項目のマージは行いません。1つのパラメータを変更する目的で部分的なparameters配列を送信した場合、そのパラメータは編集されません。送信したパラメータのみで配列全体が置き換えられ、残りは消滅します。
正しいシーケンスは、常に完全なオブジェクトに対する読み込み-変更-書き込みです。
# 1. 完全な現在のリソースを取得します
apidog endpoint get <endpointId> --project <projectId>
# 2. 完全な構造をローカルで編集します（変更しないすべてのフィールドを保持します）
# 3. スキーマに対してオブジェクト全体を検証します
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. 完全なオブジェクトを書き戻します
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
エージェントへの指示には、簡潔な言葉で次のように記してください。updateに部分的なオブジェクトを送信してはなりません。常に完全なリソースを取得し、それを変更して、全体を返送してください。getステップをスキップするエージェントは、フィールドを密かに削除します。最初にcli-schema validateを実行するエージェントは、プロジェクトに到達する前に自身の誤りを発見します。
安全な道筋：AIブランチでエージェントに作業させる
エージェントにメインブランチへの直接編集権限を与えることもできます。しかし、少なくとも最初はそうしないでください。Apidogには、まさにこの目的のために設計された専用の分離メカニズム、AIブランチがあります。エージェントはソースブランチに触れることなくリソースを変更し、あなたが許可するまで何もマージされません。それをAPI仕様のプルリクエストと考えてください。
ステップ1：AIブランチを作成する
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
命名規則はai/YYYYMMDD-from-source-featureとすることで、ブランチの出所と目的が一目でわかるようになります。--fromの値は、メインブランチまたは通常のSprintブランチである必要があり、一般的なブランチであってはいけません。便利な点の1つとして、ソースとの差分がないAIブランチは24時間後に自動アーカイブされるため、放棄された実験は自動的に整理されます。
ステップ2：エージェントが編集するリソースをインポートする
AIブランチは空の状態で開始されます。ソースブランチを自動的にクローンすることはありません。エージェントが既存のエンドポイントやスキーマを編集できるようにするには、pick-toを使ってそのリソースをブランチに取り込んでください。
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
エージェントがブランチ上で新規に作成するリソースにはこれを行う必要はありません。変更または削除を意図する既存のリソースのみです。これは人々が忘れがちなステップです。これをスキップすると、エージェントは空のブランチを持ち、編集するものが何もなくなります。
ステップ3：エージェントに変更を行わせる
ここで、エージェントは以前の読み込み-変更-書き込みループを実行しますが、--branchはAIブランチを指します。すべての編集は分離されています。
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
この間、メインブランチは一切変更されません。エージェントが何か間違ったことをしても、影響範囲は使い捨てブランチ一つに限定されます。
ステップ4：レビューし、マージする
AIブランチの変更は自動的に書き戻されることはありません。エージェントが作業を終えたら、あなたがどうするかを決定します。ターゲットが保護されている場合は、直接マージするのではなく、マージリクエストを開いてください。
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
差分をレビューし、承認すると、検証済みの変更がメインブランチに適用されます。CLIからの直接マージには、ソースブランチとターゲットブランチの両方に対する直接編集権限が必要です。メインブランチが保護されている場合は、merge-requestを使用し、Apidogクライアントで承認することを推奨します。
実例：フィールドを安全に名前変更する
抽象的なルールはうなずくのは簡単ですが、適用するのは難しいです。具体的な例を挙げます。RefundデータモデルのamountをamountCentsに名前変更したいとします。これは、金額の単位を整数セントに移行するためです。
エージェントに次のように指示します。「RefundスキーマのamountフィールドをamountCentsに名前変更し、整数型にしてください。」そのルールに従って、エージェントは次のことを行います。
# 1. AIブランチ上の完全な現在のスキーマを取得します
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
完全なオブジェクトが返され、全体のjsonSchemaを編集します。触れていないすべてのフィールドはそのまま保持されます。
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
注目すべきは、何が起こらなかったかです。変更されたプロパティ1つだけを送信したわけではありません。updateは置き換えを行うため、orderIdとreasonが手付かずのままでスキーマ全体を送信しました。その後：
# 2. 完全なオブジェクトを検証します
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. AIブランチに書き戻します
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
あなたはAIブランチの差分（1つのフィールドが名前変更され、他は何も変更されていない）をレビューし、マージします。これが規律のすべてです。完全なオブジェクト、検証済み、ブランチ上、レビュー後にマージ。
マージ前に破壊的変更にフラグを立てる
必須フィールドの名前変更は破壊的変更です。amountを送信するすべてのクライアントは、今後検証に失敗します。優れたエージェントの指示セットは、モデルが黙ってマージするのではなく、そのことを伝えるようにします。エージェントのルールにこれを追加してください。
仕様の変更をマージする前に、分類してください：
- 非破壊的（新しいオプションフィールド、新しいエンドポイント、制約の緩和）→ 要約してマージリクエストに進みます。
- 破壊的（フィールドの名前変更/削除、新しい必須フィールド、型の厳格化）→ 停止します。
破壊的変更と影響を受けるエンドポイントを報告し、明示的な人間の承認を待ちます。
AIブランチがあるからこそ、これが安全に実施できます。自動的にマージされるものはないため、「停止して報告」は、すでに発生した書き込みとの競争ではなく、本当のチェックポイントとなります。
代わりにOpenAPIファイルから更新する
コードから生成された、別の場所で編集された、または他のチームから渡されたOpenAPIファイルとして、変更がすでに存在することがあります。フィールドごとに編集を再実行するのではなく、エージェントはファイルをインポートしてプロジェクトと調整できます。
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
importはOpenAPI 3.x、Swagger 2.0、Postmanなどを受け入れます。まずAIブランチに対して実行し、メインに到達する前に、インポートされる仕様の変更内容を確認できるようにしてください。マージ後、調整された仕様をエクスポートし直して結果を確認します。
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
この方法は、信頼できる情報源がApidogの外部にあり、それを同期させる場合に最適です。フィールドごとのupdate方法は、Apidogが信頼できる情報源であり、ピンポイントな変更を行う場合に最適です。
エージェントが間違った場合：ロールバック
AIブランチで作業する理由は、間違いを簡単に元に戻せるからです。エージェントが望まない変更を生成しても、あなたはそれをマージしていないため、メインブランチはすでに正しい状態です。ブランチをアーカイブして次に進むだけです。
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
承認された差分がないAIブランチは24時間後に自動アーカイブされるため、忘れられた実験でさえも自動的に整理されます。これを、エージェントがメインブランチを直接編集する場合と比較してください。その場合、間違ったupdateはすぐに適用され、頼れるのはごみ箱か手動での元に戻す作業しかありません。ブランチは官僚主義ではありません。それは「元に戻す」ボタンなのです。
権限に関する注意点
updateまたはimportがブロックされた場合、プロジェクトで外部AI編集権限が無効になっています。これは意図的なゲートであり、上記のAIブランチフローがその解決策です。エージェントが分離されたブランチを編集し、あなたがマージを承認します。直接編集を許可したい場合は、プロジェクト設定 → 機能設定 → AI機能設定（Apidogクライアント2.8.32以降）で切り替えることができます。エージェントが権限の壁にぶつかった場合、黙って回避策を選択させるのではなく、その選択を人間に提示するようにしてください。
よくある落とし穴
- 部分的な更新がフィールドを消去した。 最も破壊的で一般的な間違いです。
updateは置き換えであり、マージではありません。完全なオブジェクトを取得し、全体を編集し、検証してから書き込みます。フィールドが消えた場合、エージェントが部分的なペイロードを送信したことになります。 - AIブランチで既存のリソースをインポートせずに編集した。 ブランチは空の状態で開始されます。最初に
pick-toでリソースを取り込むか、さもないとエージェントは編集するものが何もありません。 - AIブランチの
--fromが間違っている。 ソースはメインブランチまたはSprintブランチである必要があり、一般的なブランチであってはいけません。これを間違えると、branch createコマンドがエラーを出します。 - 検証のスキップ。
cli-schema validateは、あなたのマシン上で不正なペイロードを捕捉します。検証せずに書き込むエージェントは、タイプミスを失敗したAPI呼び出しに変えたり、さらに悪いことに、間違ったマージを引き起こしたりします。 - 破壊的変更を黙ってマージした。 最初に分類するルールがなければ、エージェントは喜んで必須フィールドの名前を変更し、マージしてしまいます。破壊的変更の検出を明示的なチェックポイントにしてください。
よくある質問
- エージェントにメインブランチを直接編集させられますか？ 外部AI編集権限を有効にすることで可能です。しかし、AIブランチで開始する方が安全です。マージを承認するまで、何もメインに適用されません。直接編集は、リスクが低く、信頼性の高い自動化のためにとっておきましょう。
branch mergeとmerge-requestの違いは何ですか？branch mergeは変更をすぐに書き込み、両方のブランチに対する直接編集権限が必要です。merge-requestはレビュー可能なリクエストを開くため、メインブランチが保護されている場合に適切な選択肢です。- エージェントはApidogデスクトップアプリを必要としますか？ いいえ、CLIはスタンドアロンです。アプリは、外部AI編集権限設定を切り替えるためだけに使用され、これは一度限りの設定です。
- エージェントがフィールド名を捏造しないようにするにはどうすればよいですか？
cli-schema get→validateループがガードレールとなります。捏造されたフィールドを含むペイロードは、プロジェクトに到達する前にローカルで検証に失敗します。
まとめ
エージェントにAPI仕様を更新させるのは、次の3つの条件が満たされていれば安全です。分離されたAIブランチで作業すること、すべての更新をパッチではなく完全な読み込み-変更-書き込みとして扱うこと、そして人間がマージを承認することです。Apidog CLIはこれら3つすべてをコマンドとして提供します。これにより、ループ全体（編集、検証、レビュー）がスクリプト可能で監査可能になり、誤った変更はarchiveコマンド一つで消去できます。
AIブランチを設定し、エージェントに読み込み-変更-書き込みルールと破壊的変更のチェックポイントを伝えれば、仕様のメンテナンスは、延期し続ける厄介な作業ではなく、あなたが承認する差分へと変わります。CLIを入手するためにApidogをダウンロードし、これをエージェントにドキュメントを作成させることと組み合わせることで、作成からメンテナンスまでの完全なループをカバーできます。