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では、ドキュメント操作をスクリプト可能なコマンドとして実行でき、エージェントが処理しやすい構造化JSONも返されます。

GUIやMCPサーバーではなく、なぜCLIなのか

エージェントがAPIドキュメントに関わる方法は主に3つあります。

アプローチ 方向 実行者 差分レビュー
GUI ブラウザで編集 人間 不可
MCPサーバー 仕様を読み込み、コードを生成 エディタ内のエージェント コードリポジトリでは可能、ドキュメント自体ではない
CLI ドキュメント自体を作成・公開 ターミナル内のエージェント 可能。コマンドをログに残せる

MCPサーバーは、API定義を読み込ませてクライアントコードを生成する用途に適しています。CursorのMCPによるドキュメントフローもその例です。

一方で、ここで扱うのは「ドキュメントを読む」フローではなく、「ドキュメントを作る」フローです。エンドポイント、Markdownガイド、公開サイトを作成するにはCLIが向いています。

CLIを使う利点は次のとおりです。

  • 決定論的: 同じコマンドは同じ結果を返す
  • スクリプト可能: CIやエージェントのタスクループに組み込める
  • JSONレスポンス: agentHints.nextSteps を読み、次の操作を判断できる

エージェントが推測で操作するのではなく、CLIが返す次のアクション候補に従える点が重要です。

エージェントの環境をセットアップする

まず、CLIをインストールして認証します。インストールガイドではNode.jsのバージョンやPATH設定を、認証ガイドではトークンやCIシークレットを確認できます。

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Apidog CLIのインストールと認証

トークンはApidogアプリで次の場所から取得します。

ユーザーアバター → アカウント設定 → APIアクセストークン

ログイン後はトークンがローカルに保存されるため、以降のCLI呼び出しで毎回渡す必要はありません。

APIアクセストークンの取得画面

書き込み操作ではプロジェクトIDが必要です。プロジェクト設定の「基本設定」で確認するか、次のコマンドで取得します。

apidog project list
Enter fullscreen mode Exit fullscreen mode

シェルコマンドを実行できるエージェントであれば利用できます。たとえば、Claude Code、Cursor、Codexなどです。

CursorでのApidog CLI利用例

CodexでのApidog CLI利用例

エージェントが従うべき書き込み手順

リソースを作成するCLIコマンドはJSONファイルを受け取ります。エージェントにJSONペイロードを記憶だけで作らせないでください。誤ったフィールド名や不足フィールドが、実行失敗の主な原因になります。

すべての書き込みで、次の4ステップを徹底します。

# 1. CLIからペイロードのスキーマを取得する
apidog cli-schema get doc-create

# 2. スキーマに従ってJSONファイルを作成する

# 3. 書き込み前にローカルで検証する
apidog cli-schema validate doc-create --file ./doc.json

# 4. 検証後に実際の作成コマンドを実行する
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

このループをエージェントのシステムプロンプト、CLAUDE.md、または.cursorrulesに追加してください。

Apidog CLI rules:
- Never hand-write a JSON payload. Run `apidog cli-schema get <key>` first and build from that schema.
- Validate every file with `apidog cli-schema validate <key> --file <path>` before any create or update.
- Always pass --project <id> on write commands.
- Read the `agentHints.nextSteps` field in each JSON response to choose the next command.
- If a write comes back blocked by permissions, stop and ask the human; do not pick a workaround.
Enter fullscreen mode Exit fullscreen mode

日本語で運用ルールを書く場合は、次のようにします。

Apidog CLIのルール:
- JSONペイロードを手書きしない。必ず最初に `apidog cli-schema get <key>` を実行し、取得したスキーマから作成する。
- create または update の前に、必ず `apidog cli-schema validate <key> --file <path>` で検証する。
- 書き込みコマンドには常に `--project <id>` を指定する。
- JSONレスポンスの `agentHints.nextSteps` を読み、次のコマンドを選ぶ。
- 権限不足で書き込みがブロックされたら回避策を試さず、人間に確認する。
Enter fullscreen mode Exit fullscreen mode

ステップ1：エンドポイントとスキーマからリファレンスを作成する

ApidogのAPIリファレンスは、プロジェクト内のエンドポイントとデータスキーマをもとに生成されます。

たとえば、エージェントに次のように依頼します。

「注文IDと金額を受け取る POST /refunds エンドポイントを追加し、成功応答と検証エラー応答をドキュメント化してください。」

まず、再利用可能なデータモデルを作成します。schema-create のスキーマを確認してください。

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

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

検証してから作成します。

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

続いてエンドポイントを作成します。endpoint-create のスキーマを確認し、作成したデータモデルを #/definitions/{schemaId} 形式の $ref で参照します。

apidog cli-schema get endpoint-create
Enter fullscreen mode Exit fullscreen mode

refunds-endpoint.json の例です。

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": {
      "$ref": "#/definitions/<refundSchemaId>"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode 
apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Enter fullscreen mode Exit fullscreen mode

これで /refunds のAPIリファレンスは、チームが編集するエンドポイント定義と同じソースから生成されます。別途リファレンスをエクスポートする必要はありません。エンドポイントを作成した時点で、プロジェクト内のリファレンスとして利用できます。

ステップ2：リファレンスだけでなくガイドも書く

スキーマから生成されるリファレンスだけでは不十分です。クイックスタート、認証チュートリアル、移行ガイドなどの説明文も必要です。

Apidogでは、これらを doc コマンドグループで管理します。ドキュメントツリー内のMarkdownページとして作成されます。

doc-create では name が必須です。content にMarkdownを指定し、folderId で配置先を指定します。ルートフォルダは 0 です。

quickstart.json の例です。

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}
Enter fullscreen mode Exit fullscreen mode

作成前に、既存のドキュメントツリーを確認します。

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Enter fullscreen mode Exit fullscreen mode

たとえば、次の依頼をエージェントに渡せます。

「新規開発者がAPIキーを取得して最初の払い戻しを実行するまでのクイックスタートを書いてください。」

エージェントはMarkdownを作成し、doc-create のペイロードに入れ、検証後にドキュメントを作成できます。ブラウザ操作やコピー＆ペーストは不要です。

ステップ3：ドキュメントサイトを公開する

リファレンスとガイドを作成したら、ターミナルから公開できます。ここでは3つのコマンドグループを区別してください。

  • doc: プロジェクトのAPIツリー内にあるMarkdownドキュメント
  • docs-site: ホスト・公開されるドキュメントサイト
  • shared-doc: パートナーなどに送る共有リンク。完全なサイトではない

公開サイトを扱う場合は 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
Enter fullscreen mode Exit fullscreen mode

ターミナルから公開サイトを定義・更新したい場合は docs-site、共有用URLだけが必要な場合は shared-doc を選びます。どちらもCLIコマンドなので、ドキュメント変更後の公開処理をエージェントやCIのステップとして実行できます。

ステップ4（任意）：ポータブルなコピーをエクスポートする

ドキュメントをファイルとして出力したい場合は export を使います。HTML、Markdown、OpenAPIを出力できます。

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

複数サービスを1プロジェクトで管理している場合は、--scope、--api-ids、--folder-ids を使って対象を絞り込めます。

apidog export --help
Enter fullscreen mode Exit fullscreen mode

これにより、サービスごとに個別のドキュメントファイルを出力できます。

完全なエンドツーエンドの例

次の依頼を考えます。

あなた: 「POST /refunds と GET /refunds/{id} を含む支払いサービスを追加しました。両方をドキュメント化し、冪等性キーを説明する短いガイドを書き、ドキュメントサイトに公開してください。」

エージェントは、スキーマ取得・検証・作成のルールに従い、次の処理を実行します。

# 共有データモデルを作成
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# 2つのエンドポイントを作成
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# 冪等性ガイドをMarkdownドキュメントとして作成
apidog doc create --project $PID --file ./idempotency-guide.json

# ドキュメントサイトを公開
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

実運用では、各 create の前に対応する cli-schema get と cli-schema validate を実行してください。

レビュー対象は、生成されたスキーマ、エンドポイント、Markdown、公開設定の差分です。ドキュメント作成に伴うコンテキストスイッチを減らし、依頼とレビューに集中できます。

エージェントループまたはCIに組み込む

すべての操作がCLIコマンドなので、CIやエージェントのタスクループに組み込めます。

以下は、プッシュごとにMarkdownリファレンスを再生成する最小構成の例です。

- name: Regenerate API docs
  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
Enter fullscreen mode Exit fullscreen mode

エージェントをCLIでエンドツーエンドに動かすパターンについては、PRDからテストループまでと、完全なAPIを構築するために5つのAIエージェントをセットアップする方法を参照してください。

基本パターンは同じです。

  1. 意図を自然言語で記述する
  2. エージェントが検証済みのCLI呼び出しへ変換する
  3. 結果の差分をレビューする

権限に関する注意点

エージェント経由の書き込みが制限される場合があります。create コマンドがブロックされた場合、そのブランチではプロジェクトの「外部AI編集権限」が無効になっている可能性があります。

対応方法は2つです。

  1. プロジェクト設定 → 機能設定 → AI機能設定で直接編集権限を有効にする
    • Apidogクライアント 2.8.32 以降
  2. エージェントを分離されたAIブランチで動かし、マージリクエストを作成する

AIブランチの運用は、API仕様の更新に関する付随ガイドで詳しく説明されています。保護ブランチ上でエージェントにドキュメントを作成させる場合にも同じ考え方を適用できます。

よくある落とし穴

  • エージェントがJSONを手動で構築した

    最も多い失敗です。cli-schema get → cli-schema validate → create を必須ルールにしてください。

  • プロジェクトIDがない

    doc、docs-site、export の呼び出しには --project が必要です。プロジェクト名ではなく、設定画面または apidog project list で取得したIDを指定してください。

  • doc、docs-site、shared-doc を混同した

    doc はMarkdownページ、docs-site は公開サイト、shared-doc は共有リンクです。書き込み前に目的を明確にしてください。

  • CIでトークンを設定していない

    apidog login は実行マシンにトークンを保存します。新しいCIランナーでは、同じジョブ内で apidog login --with-token を実行してください。トークンはシークレットで管理します。

  • 存在しないスキーマを $ref した

    #/definitions/{schemaId} を参照する前に、そのスキーマを作成する必要があります。スキーマ作成をエンドポイント作成より先に実行してください。

FAQ

Apidog CLIを実行できるAIエージェントはどれですか？

シェルコマンドを実行できるエージェントなら利用できます。Claude Code、Cursor、Codexなどのコーディングエージェントが対象です。CLIはエージェントの種類ではなく、正しいコマンドと有効なペイロードを必要とします。

有料プランが必要ですか？

いいえ。Apidogはオープンソースではありませんが、無料プランと apidog-cli で、この記事で紹介した作成・公開フローを利用できます。

エージェントが既存のドキュメントを誤って上書きすることはありますか？

create は新しいリソースを追加します。既存リソースを変更する場合は update を使います。更新操作には追加の保護が必要です。詳しくはAPI仕様の更新に関する付随ガイドを参照してください。

一般的なAIドキュメントジェネレーターと何が違いますか？

一般的なAIドキュメントツールは、コードから説明テキストを生成します。このフローでは、エンドポイント、スキーマ、ガイド、公開サイトを含むAPIプラットフォーム内で、チームが編集するライブな定義をソースとして構造化ドキュメントを作成します。

まとめ

Apidog CLIを実行できるエージェントは、後回しにされやすいドキュメント作成を担当できます。エンドポイントを作成し、ガイドを書き、公開サイトを更新するまでを、自然言語の依頼から実行できます。

信頼性を確保するルールはシンプルです。

  1. スキーマを取得する
  2. JSONを作成する
  3. 検証する
  4. 作成または更新する

エージェントにこの手順、ルールブロック、プロジェクトIDを与えれば、ドキュメントはコードの後に追いつく作業ではなく、開発フローの一部になります。ApidogをダウンロードしてCLIを入手するか、Apidog CLI完全ガイドでコマンドリファレンスを確認してください。

Top comments (0)