DEV Community

Cover image for Apidog CLIでAIエージェントがAPI仕様を自動更新する方法
Akira
Akira

Posted on • Originally published at apidog.com

Apidog CLIでAIエージェントがAPI仕様を自動更新する方法

API仕様を手作業で更新する作業は、フィールド名の変更、列挙値の追加、必須フラグの調整など、小さな変更の積み重ねです。しかし、既存のエンドポイントやクライアントとの契約を壊さず、正しい場所に反映するには厳密さが求められます。これは、ガードレールを用意したうえでAIエージェントに任せるのに適した作業です。

今すぐApidogを試す

Apidog CLIを使うと、エージェントによる仕様変更を安全に運用できます。書き込み前のスキーマ検証、作業用の分離ブランチ、レビュー後のマージという流れをCLIで実行できます。

これは、エージェントにAPIドキュメントを作成させる方法の続編です。新規作成は追加的な変更であり比較的低リスクですが、既存の契約を更新する場合は、破壊的変更を防ぐ仕組みが必要です。

CLIにおける「仕様の更新」とは

Apidogの仕様は、プロジェクト内のエンドポイントとデータスキーマの集合です。更新には主に次の3種類があります。

  • endpoint update: パス、パラメータ、レスポンスを変更する
  • schema update: エンドポイントが参照するデータモデルを変更する
  • import: OpenAPIファイルなどをインポートして既存プロジェクトへ反映する

エージェントに更新を任せる前に、次の2点をルールとして固定してください。

  1. update は部分更新ではなく置き換えである
  2. 変更はAIブランチで行い、レビュー後にマージする

最重要ルール：update は完全な置き換えである

Apidog CLIの update はJSON Patchではありません。部分的な配列やオブジェクトを送信しても、ID単位でマージされません。

たとえば、parameters 配列の一要素だけを送信すると、その要素だけが更新されるのではなく、配列全体が送信内容で置き換えられます。送らなかったパラメータは削除されます。

必ず、読み込み → 変更 → 検証 → 書き込み の順で実行してください。

# 1. 現在の完全なリソースを取得する
apidog endpoint get <endpointId> --project <projectId>

# 2. 取得した完全な構造をローカルで編集する
#    変更対象以外のフィールドも削除しない

# 3. 書き込み前にCLIスキーマで検証する
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
Enter fullscreen mode Exit fullscreen mode

エージェントへの指示には、次のルールを明示します。

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"
Enter fullscreen mode Exit fullscreen mode

ブランチ名は次の形式にすると、用途と作成元を把握しやすくなります。

ai/YYYYMMDD-from-source-feature
Enter fullscreen mode Exit fullscreen mode

--from にはメインブランチまたはSprintブランチを指定します。一般ブランチは指定できません。

また、ソースとの差分がないAIブランチは24時間後に自動アーカイブされるため、放置した実験用ブランチも整理されます。

ステップ2：編集対象の既存リソースを取り込む

AIブランチは空の状態で開始します。ソースブランチのリソースは自動コピーされません。

既存のエンドポイントやスキーマを編集する場合は、pick-to で対象リソースをAIブランチへ取り込みます。

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

新規作成するリソースには不要です。しかし、変更または削除する既存リソースは、先に取り込む必要があります。

この手順を省略すると、エージェントは空のブランチ上で編集対象を見つけられません。

ステップ3：AIブランチで読み込み・変更・書き込みを実行する

エージェントは、前述した読み込み・変更・書き込みのフローを実行します。このとき、すべてのコマンドで --branch にAIブランチを指定します。

# 現在のエンドポイント定義を取得する
apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

# 完全なオブジェクトを検証後、AIブランチへ更新する
apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

この間、メインブランチは変更されません。エージェントが誤った編集をしても、影響はAIブランチ内に限定されます。

ステップ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>
Enter fullscreen mode Exit fullscreen mode

保護されたメインブランチへ反映する場合は、直接マージではなくマージリクエストを使う運用が適しています。

branch merge には、ソースブランチとターゲットブランチの両方への直接編集権限が必要です。メインブランチが保護されている場合は、merge-request を使い、Apidogクライアントで承認してください。

実例：amount を amountCents に安全に変更する

Refund データモデルの amount を amountCents に変更し、金額を整数セントで扱うようにするケースを考えます。

エージェントへの依頼例は次のとおりです。

Refundスキーマの amount フィールドを amountCents に名前変更し、整数型にしてください。完全なスキーマを取得してから編集し、検証後にAIブランチへ更新してください。

最初に、AIブランチ上の現在のスキーマを取得します。

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

取得したオブジェクト全体を保持したまま、jsonSchema を編集します。

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

重要なのは、変更対象の amountCents だけを送信しないことです。

schema update は置き換えを行うため、orderId や reason を含むスキーマ全体を送信します。

# 完全なオブジェクトを検証する
apidog cli-schema validate schema-create --file ./refund-full.json

# AIブランチへ反映する
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

レビューでは、次を確認してください。

  • amount が amountCents へ変更されている
  • 型が integer になっている
  • orderId、reason、その他の既存定義が消えていない
  • required 配列が意図どおり更新されている

マージ前に破壊的変更を検出する

必須フィールドの名前変更は破壊的変更です。amount を送信していた既存クライアントは、変更後にバリデーションエラーになります。

エージェントには、変更の分類と停止条件を事前に与えてください。

仕様変更をマージする前に、変更を分類すること：

- 非破壊的変更
  例：任意フィールドの追加、新しいエンドポイントの追加、制約の緩和
  → 変更内容を要約し、マージリクエストを作成する。

- 破壊的変更
  例：フィールドの名前変更・削除、新しい必須フィールド、型の厳格化
  → 処理を停止する。
  → 破壊的変更の内容と影響を受けるエンドポイントを報告する。
  → 明示的な人間の承認を待つ。
Enter fullscreen mode Exit fullscreen mode

AIブランチを使っていれば、「停止して報告」は実際のチェックポイントになります。変更が自動でメインブランチへ反映されないためです。

OpenAPIファイルから仕様を更新する

変更内容がすでにOpenAPIファイルに存在する場合は、フィールド単位で更新する代わりにインポートできます。

たとえば、コード生成された仕様、別チームから共有された仕様、外部で編集された仕様を取り込む場合です。

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

import はOpenAPI 3.x、Swagger 2.0、Postmanなどを受け入れます。

まずAIブランチへインポートし、メインブランチへマージする前に差分を確認してください。マージ後は、調整済みの仕様をエクスポートして結果を検証できます。

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

使い分けは次のとおりです。

方法 向いているケース
endpoint update / schema update Apidogを信頼できる情報源とし、限定的な変更を行う場合
import 外部のOpenAPIファイルを信頼できる情報源として同期する場合

エージェントが誤った変更をした場合：ロールバック

AIブランチで作業する最大の利点は、誤った変更をメインブランチへ持ち込まずに破棄できることです。

エージェントの出力が期待どおりでなければ、AIブランチをアーカイブします。

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

まだマージしていなければ、メインブランチは変更されていません。

承認済みの差分がないAIブランチは24時間後に自動アーカイブされるため、忘れた実験用ブランチも整理されます。

メインブランチを直接編集させる場合、誤った update は即座に反映されます。その場合は、ごみ箱または手動修正に頼ることになります。AIブランチは単なる手続きではなく、安全な「元に戻す」仕組みです。

権限に関する注意点

update または import がブロックされる場合、プロジェクトで外部AI編集権限が無効になっている可能性があります。

これは意図的な制御です。その場合は、AIブランチでエージェントに作業させ、人間がマージを承認するフローを使ってください。

直接編集を許可する場合は、Apidogクライアント 2.8.32以降で次の設定を変更できます。

プロジェクト設定 → 機能設定 → AI機能設定
Enter fullscreen mode Exit fullscreen mode

エージェントが権限エラーに遭遇した場合、勝手に代替手段を選ばせるのではなく、人間へ選択肢を提示するルールを設けると安全です。

よくある落とし穴

  • 部分更新でフィールドを削除した

    update はマージではなく置き換えです。必ず完全なオブジェクトを取得し、全体を編集、検証してから更新します。

  • AIブランチへ既存リソースを取り込まずに編集しようとした

    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 と cli-schema validate を組み合わせます。捏造されたフィールドや不正な構造を含むペイロードは、プロジェクトへ送信する前にローカルで検証エラーにできます。

まとめ

AIエージェントにAPI仕様を安全に更新させるには、次の3つを守ります。

  1. 分離されたAIブランチで作業する
  2. すべての更新を完全な読み込み・変更・書き込みとして扱う
  3. 人間が差分をレビューし、マージを承認する

Apidog CLIでは、この編集・検証・レビューのループをコマンドとして実行できます。誤った変更はAIブランチをアーカイブするだけで破棄できます。

まずAIブランチを作成し、エージェントに「完全なオブジェクトを更新すること」と「破壊的変更では停止すること」を指示してください。仕様メンテナンスを、リスクのある手作業ではなく、レビュー可能な差分として扱えるようになります。

CLIを入手するにはApidogをダウンロードし、エージェントにAPIドキュメントを作成させるフローと組み合わせることで、作成から保守までの運用を構築できます。

Top comments (0)