Apidog CLIでAIエージェントにAPIドキュメントを自動生成させる方法

APIドキュメントは、誰もが重要だと認めながらも誰も担当したがらないタスクです。新しいエンドポイントがリリースされてもリファレンスは1週間遅れ、入門ガイドには2スプリント前に置き換えた認証フローが記述されています。作業は現実的ですが、反復的で先延ばしにしやすいものです。

この組み合わせ（重要、反復的、先延ばし可能）は、まさにAIエージェントが得意とするところです。エージェントがターミナルコマンドを実行できるなら、平易な言語でのリクエストだけで、エンドポイントの作成、関連する解説ガイドの執筆、そしてドキュメントサイトの公開まで可能です。Apidog CLIはそれを可能にします。すべてのドキュメントアクションはスクリプト可能なコマンドであり、エージェントが読み取って操作できる構造化されたJSON出力を提供します。

ボタン

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

エージェントがAPIドキュメントにアクセスする方法は3つあり、それぞれ異なる問題を解決します。この区別を正しく理解することが、ツールと格闘するのか、仕事のために作られたツールを使うのかの違いとなります。

アプローチ	方向	誰が実行するか	差分レビュー可能か
GUI	ブラウザでの人間の編集	人間、クリック操作	いいえ
MCPサーバー	仕様を読み込み → コードを生成	エディタ内のエージェント	コードリポジトリ内、ドキュメントではない
CLI	ドキュメント自体を作成	ターミナル内のエージェント	はい、すべてのコマンドがログに記録される

MCPサーバーは、エージェントにAPI定義を*読み込ませて*クライアントコードを生成させたい場合に非常に優れています。CursorのMCPによるドキュメントフローが典型的な例です。しかし、ここで私たちが望んでいることとは逆です。私たちはエージェントにドキュメントを*作成させる*ことを望んでいます。つまり、エンドポイントの作成、Markdownガイドの執筆、そしてサイトの公開です。

その点において、CLIは3つの点で優れています。決定論的であること。つまり、同じコマンドは同じ結果を生み出します。スクリプト可能であること。フロー全体をCIに組み込めます。そして、すべての呼び出しでJSONを返し、`agentHints.nextSteps`フィールドを含んでおり、エージェントが次に何をすべきかを指示します。この最後の点は、見た目以上に重要です。エージェントが手探りで進むのではなく、CLI自身の提案に従っていることを意味します。

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

CLIをインストールし、一度認証します。弊社のインストールガイドではNodeのバージョンとPATHについて、認証ガイドではトークンとCIシークレットについて説明しています。

npm install -g apidog-cli
apidog login --with-token <TOKEN>

トークンはApidogアプリのユーザーアバター → アカウント設定 → APIアクセストークンから取得してください。ログイン後にローカルに保存されるため、エージェントはすべての呼び出しでそれを渡す必要はありません。

すべての書き込みはプロジェクトIDに対して実行されます。プロジェクトIDはプロジェクト設定 → 基本設定で見つけることができます。または、次を実行して取得できます。

apidog project list

シェルコマンドを実行できるコーディングエージェントならどれでもここで機能します。Claude Code、Cursor、Codex、その他です。CLIはどのエージェントが呼び出しているかに関心がなく、コマンドとペイロードが正しいことだけを気にします。そして、これが全体を信頼性の高いものにする唯一のルールへとつながります。

エージェントが従うべき書き込み儀式

リソースを作成するドキュメントコマンドはJSONファイルを受け取ります。エージェントはそのJSONを記憶から手動で作成してはなりません。モデルが勝手に作成したフィールド名は、実行失敗の最大の原因です。CLIはすべての書き込みに対して正確なスキーマを提供しており、正しい手順は常に以下の4つのステップです。

# 1. Ask the CLI what the payload looks like
apidog cli-schema get doc-create

# 2. Generate the JSON file from that schema

# 3. Validate before you write (catches a missing field locally)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Only now run the real command
apidog doc create --project <projectId> --file ./doc.json

このループをエージェントの指示に組み込んでください。これにより、「モデルがフィールドを勝手に作成した」が「バリデーターが私のマシンでそれを拒否した」に変わり、クリーンな実行と失敗したビルドとの違いが生じます。以下に、エージェントのシステムプロンプトまたは`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.

この5行こそが、ドキュメントを確実に公開するエージェントと、ペイロードを推測して失敗するエージェントとを隔てるものです。

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

Apidogでは、APIリファレンスはプロジェクト内のエンドポイントとデータスキーマから生成されます。そのため、エージェントの最初の仕事はこれらを作成することです。エージェントに次のように指示するとします。

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

エージェントはまず再利用可能なデータモデルを作成し、次にそれを参照するエンドポイントを作成します。`apidog cli-schema get schema-create`を実行すると、データスキーマが`name`と標準の`jsonSchema`オブジェクトを受け取ることがわかります。そこでエージェントは`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" }
    }
  }
}

検証して作成します。

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

次にエンドポイントです。`endpoint-create`スキーマには`method`と`path`が必要で、`#/definitions/{schemaId}`の形式で`$ref`を使用して作成したばかりのデータモデルを参照できます。エージェントは`refunds-endpoint.json`を記述します。

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

これで`/refunds`のリファレンスドキュメントが、チームが編集するのと同じ定義からレンダリングされて存在します。リファレンスには個別の「ドキュメントをエクスポートする」ステップはありません。エンドポイントが着地した瞬間にプロジェクト内でライブになります。これがスキーマファーストのソースの利点です。リファレンスはスキーマそのものであるため、乖離することはありません。

ステップ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
}

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

ここがエージェントの価値が発揮されるところです。「新規開発者がAPIキーから最初の払い戻しを行うまでのクイックスタートを書いてください」と依頼すると、エージェントはMarkdownを下書きし、スキーマが期待するペイロードにそれをラップし、検証してドキュメントを作成します。ブラウザもコピペも不要です。コンテンツは単なる文字列フィールドなので、エージェントはタスクが要求する限り、長く詳細なガイドを作成できます。

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

リファレンスとガイドが揃ったら、エージェントはターミナルからも公開できます。これには2つのコマンドグループが対応しますが、一つの命名上の区別が常に人々を戸惑わせます。

`doc`: プロジェクトのAPIツリー*内*のMarkdownドキュメント（ステップ2で作成したもの）。
`docs-site`: ホストされ、公開されているドキュメントサイト。
`shared-doc`: パートナーに渡すための共有可能なリンクであり、フルサイトではない。

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

ターミナルから定義される公開サイトが必要な場合は`docs-site`を、誰かに送るリンクが必要なだけの場合は`shared-doc`を使用してください。どちらもコマンドであるため、公開はドキュメント変更後にエージェントが実行するスクリプト化されたステップになります。ホストされたサイトは、コマンドが返された瞬間に更新を反映します。

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

ドキュメントをファイルとして必要とすることもあります。つまり、他の場所でホストするためのHTMLページ、静的サイトジェネレーター用のMarkdown、またはダウンストリームに渡すためのOpenAPIです。`export`コマンドはこれら3つすべてを生成します。

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

プロジェクトが複数のサービスを保持しており、その一部のみをドキュメント化したい場合は、`apidog export --help`で出力範囲を絞るための`--scope`、`--api-ids`、`--folder-ids`フラグが表示されます。このようにして、単一のプロジェクトがサービスごとに1つのドキュメントファイルを出荷できます。

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

以下に、平易な言語でのリクエストと、それを満たすためにエージェントが実行するコマンドのループ全体を示します。

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

エージェントは、そのルールに従って以下を実行します。

# Create the shared data model
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Create both endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Author the idempotency guide as a Markdown doc
apidog doc create --project $PID --file ./idempotency-guide.json

# Publish
apidog docs-site create --project $PID --file ./docs-site.json

結果として生成された差分をレビューすると、支払いサービスはドキュメント化され、公開されています。以前はコンテキストスイッチングに費やされていた午後が、リクエストとレビューの時間に変わります。

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

すべてのステップがコマンドであるため、フロー全体を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

CLIに対してエージェントをエンドツーエンドで実行するより詳しい内容については、PRDからテストループまでと完全なAPIを構築するために5つのAIエージェントをセットアップする方法を参照してください。どちらのパターンもここでのものと同じです。意図を記述し、エージェントがそれを検証済みのCLI呼び出しに変換させ、結果をレビューします。

権限に関する注意点

エージェントを介したプロジェクトへの書き込みは制限される場合があります。`create`コマンドがブロックされた場合、そのブランチではプロジェクトの「外部AI編集権限」が無効になっています。誠実な選択肢は2つあります。プロジェクト設定 → 機能設定 → AI機能設定（Apidogクライアント2.8.32以降）で直接編集権限を有効にするか、エージェントに分離されたAIブランチで作業させ、マージリクエストを開くかです。API仕様の更新に関する付随ガイドでは、AIブランチのフローが詳細に説明されており、エージェントが保護されたブランチでドキュメントを*作成する*場合にも同様に適用されます。

よくある落とし穴

エージェントがJSONを手動で構築した。 これが最大の失敗です。エージェントの指示で`cli-schema get` → `cli-schema validate` → `create`を強制し、推測ではなく実際のスキーマに基づいて動作するようにしてください。
プロジェクトIDの欠落。 すべての`doc`、`docs-site`、`export`呼び出しには、読み取り可能なプロジェクト名ではなく、設定からのIDである`--project`が必要です。「エラーが発生した」という報告のほとんどはこれです。
`doc`、`docs-site`、`shared-doc`の混同。 これらはツリー内のMarkdownページ、ホストされたサイト、共有リンクという3つの異なるものです。エージェントに、書き込み前にタスクが何を意味しているかを確認させてください。
CIでトークンが設定されていない。 `apidog login`はトークンを実行するマシンに保存します。新しいCIランナーにはトークンがないため、どのコマンドの前に同じジョブで`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を実行できるエージェントは、人々が常に後回しにするドキュメントの作成部分を担当できます。つまり、エンドポイントを作成し、それに関するガイドを執筆し、サイトを公開します。すべて平易な言語のリクエストから行われ、すべての書き込みはスキーマ検証によって保護されます。あなたの役割は、ドキュメントの作成から差分のレビューへと変わります。

それを信頼性の高いものにする唯一のルールは、書き込みの儀式です。スキーマを取得し、検証し、それから作成します。エージェントにそのループ、上記の5行のルールブロック、およびプロジェクトIDを与えれば、ドキュメントはコードの後ろに付いてくる面倒な作業ではなくなります。ApidogをダウンロードしてCLIを入手するか、Apidog CLI完全ガイドで完全なコマンドリファレンスを参照してください。

ボタン