DEV Community: Akira

カスタムClaudeコードサブエージェントの作り方 (設定ガイド)

Akira — Tue, 09 Jun 2026 04:22:45 +0000

あらゆる単一のAIコーディングセッションには、コンテキストウィンドウという限界があります。大規模なリファクタリング、複数回のテスト出力、コードレビューを1つの会話に詰め込むと、エージェントは重要な文脈を見失いやすくなります。Claude Codeのサブエージェントは、この問題を分割して扱うための仕組みです。1つのエージェントがすべてを同じコンテキストで処理するのではなく、独自のコンテキストウィンドウ、独自の指示、独自のツール権限を持つ専門ワーカーを起動します。この記事では、カスタムサブエージェントの作成方法、フロントマターの各フィールド、Claudeが委任先を決める仕組み、コードレビューとAPIテスト作成を並行実行する実用的な構成を説明します。

今すぐApidogを試す

TL;DR

Claude Codeサブエージェントは、.claude/agents/ にYAMLフロントマター付きのMarkdownファイルを置くことで作成します。

必要な要素は次のとおりです。

name: サブエージェントの識別子
description: Claudeがいつ委任するかを判断する説明
tools: 任意のツール許可リスト
model: 任意のモデル指定
Markdown本文: サブエージェントのシステムプロンプト

各サブエージェントは独自のコンテキストウィンドウで実行されるため、コンテキストの分離、並列処理、専門化ができます。Claudeはdescriptionに基づいて自動委任するか、名前指定で明示的に呼び出します。

60秒でわかるサブエージェント

サブエージェントは、メインのClaude Codeエージェントがタスクを渡す別のエージェントインスタンスです。

イメージとしては、メインエージェントがリードエンジニアで、サブエージェントは必要に応じて呼び出される専門担当者です。

主な特徴は3つです。

独自のコンテキストウィンドウ

サブエージェントは渡されたタスクだけで開始されます。中間調査やログ出力がメインスレッドを汚しません。
カスタムシステムプロンプト

セキュリティ観点でレビューする、既存のテスト規約に従う、API仕様を優先する、といった振る舞いを明確に指定できます。
構成可能なツール権限

レビュー専用エージェントには読み取りだけを許可し、テスト作成エージェントには必要な書き込みやBash実行だけを許可できます。

このガイドでは、概念よりも実装に焦点を当てます。

サブエージェントを使う理由

1. コンテキストを分離できる

長時間のセッションでは、ファイル読み込み、テスト実行、調査ログ、試行錯誤がコンテキストを消費します。

サブエージェントに大きな作業を委任すると、その中間作業はサブエージェント側に閉じ込められます。メインエージェントには、最終的な要約や判定だけが返ります。

たとえば、コードレビューで大量のファイルを読む場合でも、メインスレッドには次のような結果だけを返せます。

判定: 修正が必要

問題:
1. src/orders/service.ts:42
   認証済みユーザーの所有権チェックが不足しています。

2. src/orders/schema.ts:18
   quantity が 0 のケースを拒否していません。

2. 並列処理できる

独立した作業は順番に実行する必要がありません。

たとえば、新しいAPIエンドポイントを実装した後に、次の2つを同時に走らせられます。

code-reviewer: 差分をレビューする
api-test-writer: APIテストを作成・実行する

レビューが終わるまでテスト作成を待つ必要はありません。

3. 専門化できる

汎用エージェントは多くのことをこなせますが、厳密なレビューやテスト設計では専用プロンプトのほうが安定します。

たとえば、レビュー担当には次のような方針を固定できます。

正確性のバグを優先する
セキュリティ問題を見落とさない
推測ではなく、ファイルと行番号を引用する
軽いスタイル指摘よりも実害のある問題を優先する

テスト担当には次のような方針を固定できます。

OpenAPI仕様を読む
成功系、検証エラー、認証エラーを必ず含める
ステータスコードとレスポンススキーマを検証する
テストを実行して合否を報告する

カスタムサブエージェントの作成方法

サブエージェントはMarkdownファイルです。

プロジェクト単位で使う場合は次に配置します。

.claude/agents/

個人設定として使う場合は次に配置します。

~/.claude/agents/

基本構造は次のとおりです。

---
name: エージェント名
description: "Claudeがいつこのエージェントを使うべきか"
tools: Read, Grep, Glob
model: sonnet
---

ここにシステムプロンプトを書く。

例: コードレビュアー

.claude/agents/code-reviewer.md を作成します。

---
name: code-reviewer
description: バグ、セキュリティ問題、規約違反についてコード変更をレビューします。コードの記述または編集後に使用します。
tools: Read, Grep, Glob
model: sonnet
---

あなたはシニアコードレビュアーです。差分またはファイルセットが与えられた場合：

1. 正確性のバグ、セキュリティホール、見落とされたエッジケースを探します。
2. コードがプロジェクトの既存の規約に合致しているか確認します。
3. 信頼性の高い問題のみを、深刻度順に報告します。

出力形式：

- 判定: 承認 / 修正が必要
- 重大な問題
- 軽微な問題
- 確認したファイル
- 次に行うべき修正

具体的に記述してください。可能な限りファイルと行を引用してください。安易に承認しないでください。

フロントマターの意味

フィールド	必須	役割
`name`	必須	サブエージェントを呼び出す識別子
`description`	必須	Claudeが自動委任するかを判断する説明
`tools`	任意	サブエージェントに許可するツール
`model`	任意	使用するモデル

特に重要なのはdescriptionです。

悪い例:

description: コードレビューア

良い例:

description: バグ、セキュリティ問題、規約違反についてコード変更をレビューします。コードの記述または編集後に使用します。

descriptionはラベルではなく、委任トリガーとして書きます。

toolsは最小権限にする

レビュー専用エージェントにWriteを渡す必要はありません。

tools: Read, Grep, Glob

テスト作成エージェントには、テストファイルを書き込む必要があるためWriteが必要です。テスト実行が必要ならBashも必要です。

tools: Read, Grep, Write, Bash

toolsを省略すると、メインエージェントのツールを継承します。自動化や無人実行に近い用途では、明示的な許可リストを推奨します。

サブエージェントの呼び出し方

サブエージェントの呼び出し方法は2つあります。

1. 自動委任

Claudeは利用可能なサブエージェントのdescriptionを読み、タスクに一致すると自動的に委任します。

たとえば、code-reviewerの説明に次のように書いている場合:

description: バグ、セキュリティ問題、規約違反についてコード変更をレビューします。コードの記述または編集後に使用します。

コード編集後にClaudeが自動でレビューを依頼する可能性があります。

2. 明示的な呼び出し

委任を確実にしたい場合は、名前で指定します。

オーダーモジュールの変更について code-reviewer サブエージェントを使用してください。

テスト作成を明示する場合:

新しいPOST /ordersエンドポイントについて api-test-writer サブエージェントを使用してAPIテストを作成し、実行してください。

明示的に呼び出すと、どの専門エージェントを使うかを人間側で制御できます。

サブエージェント vs. エージェント SDK vs. 動的ワークフロー

ツール	制御モデル	最適な用途
サブエージェント	モデルがいつ委任するかを決定、または人間が指定	セッション内の専門化と軽い並列処理
動的ワークフロー	モデルが単一セッションで大規模なファンアウトをオーケストレート	多数の並列タスク、広範囲の調査
エージェント SDK	開発者がコードで制御フローを記述	決定論的ループ、スケジュール実行、無人実行

サブエージェントは、Claude Codeで対話しながら専門作業を分担したい場合に向いています。

一方、決定論的な制御フローやスケジュール実行が必要な場合は、Agent SDKでオーケストレーションを書くほうが適しています。

実例: 並行レビューとAPIテスト作成

ここでは、新しいオーダー作成エンドポイントを実装した後の流れを想定します。

必要な作業は次の2つです。

コードレビュー
APIテスト作成と実行

この2つは独立しているため、並行実行できます。

1. コードレビュアーを定義する

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: バグ、セキュリティ問題、規約違反についてコード変更をレビューします。コードの記述または編集後に使用します。
tools: Read, Grep, Glob
model: sonnet
---

あなたはシニアコードレビュアーです。差分またはファイルセットが与えられた場合：

1. 正確性のバグ、セキュリティホール、見落とされたエッジケースを探します。
2. コードがプロジェクトの既存の規約に合致しているか確認します。
3. 信頼性の高い問題のみを、深刻度順に報告します。

出力形式：

- 判定
- 重大な問題
- 軽微な問題
- 修正提案
- 確認したファイル

具体的に記述してください。ファイルと行を引用してください。安易に承認しないでください。

2. APIテストライターを定義する

.claude/agents/api-test-writer.md

---
name: api-test-writer
description: 新規または変更されたエンドポイントのAPIテストケースを記述します。エンドポイントが実装された後に使用します。
tools: Read, Grep, Write, Bash
model: sonnet
---

あなたはプロジェクトのOpenAPI仕様に対してAPIテストを記述します。

1. 仕様とエンドポイントの実装を読み込みます。
2. 成功、検証エラー、認証エラーをカバーするテストを記述します。
3. ステータスコードをアサートし、レスポンスボディをスキーマに対して検証します。
4. テストスイートを実行し、合否と理由を報告します。

出力形式：

- 追加または変更したテストファイル
- カバーしたケース
- テスト実行結果
- 失敗した場合の原因
- 次に修正すべき点

3. Claude Codeで並行実行を依頼する

次のように依頼します。

POST /orders エンドポイントの実装が完了しました。

次を並行して実行してください。

1. code-reviewer サブエージェントで差分をレビューする
2. api-test-writer サブエージェントでAPIテストを作成し、実行する

最後に、レビュー結果とテスト結果をまとめてください。

期待する返却結果は次のような構造です。

レビュー結果:
- 判定: 修正が必要
- 重大な問題: 1件
- 軽微な問題: 2件

テスト結果:
- 追加したテスト: tests/orders/create-order.test.ts
- 成功系: PASS
- 検証エラー: PASS
- 認証エラー: FAIL

次のアクション:
1. 認証なしリクエストで401を返すように修正
2. quantityの境界値テストを追加

この構成のポイントは、テスト担当サブエージェントを「検証ゲート」として使うことです。

エージェントが「実装できた」と判断するだけでは不十分です。APIテストを実行し、ステータスコードとレスポンススキーマを検証することで、実際に動くかを確認します。

Apidogを使っているチームであれば、サブエージェントをApidogのテストシナリオに向け、レスポンスをスキーマ検証するゲートとして利用できます。ライブエンドポイント呼び出しをApidog AIエージェントデバッガー経由で確認すれば、人間のテスターと同じようにリクエストとレスポンスを調査できます。

ベストプラクティス

1. サブエージェントごとに責任を1つにする

良い分割:

code-reviewer: レビューだけ
api-test-writer: APIテスト作成と実行だけ
security-auditor: セキュリティ観点の監査だけ
docs-writer: ドキュメント作成だけ

避けるべき分割:

review-test-docs-and-fix-everything

何でも屋のサブエージェントは、メインエージェントをもう1つ作るのとほぼ同じです。

2. descriptionはトリガーとして書く

悪い例:

description: テスト担当

良い例:

description: 新規または変更されたエンドポイントのAPIテストケースを記述します。エンドポイントが実装された後に使用します。

Claudeが「いつ使うべきか」を判断できるように書きます。

3. 最小権限を付与する

レビュー専用:

tools: Read, Grep, Glob

テスト作成と実行:

tools: Read, Grep, Write, Bash

必要がないサブエージェントにWriteやBashを渡さないでください。

4. タスクに応じてモデルを固定する

機械的な作業には高速で安価なモデルを使い、難しい推論が必要な作業には強力なモデルを割り当てます。

例:

model: sonnet

モデル指定は任意ですが、コストと速度を制御したい場合に有効です。

5. 出力形式を固定する

サブエージェントには、毎回同じ形式で報告させます。

例:

出力形式：

- 判定
- 重大な問題
- 軽微な問題
- 変更したファイル
- テスト結果
- 次のアクション

構造化された結果は、メインエージェントが次の作業に使いやすく、人間も判断しやすくなります。

6. ネストを深くしすぎない

サブエージェントが別のサブエージェントを呼び、さらにその先で別のサブエージェントを呼ぶ構成は、追跡が難しく、コストも増えます。

基本は浅い構成にします。

メインエージェント
├── code-reviewer
└── api-test-writer

サブエージェントを使うべき時

サブエージェントは、すべての作業に使うものではありません。

次の条件を満たすタスクに向いています。

範囲が明確
独立している
中間作業が多い
並行実行する価値がある
結果を要約で返せる

適した例:

コードレビュー
APIテスト作成
テストスイート実行
バグ再現
セキュリティ監査
ドキュメント生成
仕様との差分確認

サブエージェントを使わないほうがよい時

次のような作業では、サブエージェントを起動してもメリットが小さいです。

1行の修正
変数名の変更
すでにメインエージェントが必要な文脈を持っている作業
メイン作業と密結合している修正
順番に進める必要がある作業

たとえば、タイポ修正のためにサブエージェントを起動すると、ハンドオフのコストだけが増えます。

経験則は次のとおりです。

1段落で説明できるほど自己完結していて、並行実行する価値がある作業は委任する。小さく密結合した作業はメインスレッドに残す。

よくある間違い

曖昧なdescriptionを書く

description: レビュー用

これではClaudeがいつ使うべきか判断しにくくなります。

description: コード変更後に、バグ、セキュリティ問題、規約違反をレビューするために使用します。

このように、使用条件を含めます。

1つのサブエージェントに詰め込みすぎる

レビュー、テスト、修正、ドキュメント作成を1つにまとめると、専門化のメリットが失われます。

責任ごとに分割してください。

toolsを未設定のままにする

toolsを省略すると、メインエージェントのツールを継承します。

信頼できる手動作業では問題にならない場合もありますが、自動化に近い用途ではリスクになります。

検証サブエージェントを用意しない

レビューだけでは、実際に動くかを保証できません。

APIやバックエンド変更では、テストを実行するサブエージェントを用意してください。

サブエージェントをSDKの代わりに使う

サブエージェントはセッション内でモデルによりディスパッチされます。

決定論的なスケジュール実行や無人実行が必要な場合は、Agent SDKで制御フローを書くほうが適しています。

よくある質問

Claude Codeサブエージェントとは何ですか？

メインのClaude Codeエージェントがタスクを委任する、別のエージェントインスタンスです。各サブエージェントには、独自のコンテキストウィンドウ、システムプロンプト、ツール権限があります。

Claude Codeサブエージェントはどのように作成しますか？

.claude/agents/ または ~/.claude/agents/ にMarkdownファイルを作成します。

YAMLフロントマターにname、description、任意のtools、任意のmodelを書き、本文にシステムプロンプトを書きます。

Claudeはどのサブエージェントを使うかをどう決めますか？

各サブエージェントのdescriptionを読み、タスクに一致するものへ自動委任します。名前を指定して明示的に呼び出すこともできます。

サブエージェントとClaude Agent SDKの違いは何ですか？

サブエージェントはClaude Codeセッション内で使う専門エージェントです。Agent SDKは、開発者がコードで制御フローを書くための仕組みです。

対話的な専門化にはサブエージェント、決定論的な自動実行にはSDKが向いています。

サブエージェントは並行して実行できますか？

はい。独立したタスクであれば、複数のサブエージェントを同時にディスパッチできます。レビュー、テスト、ドキュメント作成を順番ではなく並行して進められます。

サブエージェントはAPIテストにどう役立ちますか？

OpenAPI仕様に対してAPIテストを作成し、実行するサブエージェントを定義できます。これにより、エンドポイントが「完成したように見える」だけでなく、実際に仕様どおり動作するかを検証できます。

ApidogのようなAPIテストプラットフォームに接続すれば、レスポンスのスキーマ検証を含む検証ゲートとして使えます。

まとめ

Claude Codeサブエージェントは、1つのコンテキストウィンドウにすべてを詰め込む問題を解決します。各タスクに独自のコンテキスト、指示、ツールを与えることで、単一の過負荷なエージェントを、並行して作業する小さな専門チームに変えられます。

最初は次の2つから始めるのが実用的です。

code-reviewer
api-test-writer

それぞれに明確なdescriptionを書き、必要なツールだけを許可し、テスト担当には実際のAPIテストを実行させます。

APIエンドポイントを扱う場合は、テストサブエージェントをスキーマ検証できるテストゲートに接続してください。Apidogを使えば、エージェントが書いたコードを人間が読む前に、APIが仕様どおり動作するかを確認しやすくなります。

Postmanはチームで使うと高すぎる？最適な代替ツールは？

Akira — Mon, 08 Jun 2026 10:50:44 +0000

最近Postmanの料金ページを開いて、「共同作業するためだけに料金を払う必要があるのか？」と感じたチームは少なくありません。Postmanは依然として有力なAPIツールですが、チーム利用のコストを見直すタイミングなら、代替ツールの選定基準と移行手順を明確にしておくべきです。

Apidogを今すぐ試す

多くのAPIチームにとって、Postmanはこれまで手軽なデフォルトツールでした。コレクションの作成、リクエスト共有、環境管理、テスト作成、チームメイトの招待を1つの画面で扱えたからです。しかし、チームでの共同作業が有料プラン前提になると、コスト計算はすぐに変わります。一般的に議論される月額ユーザーあたり19ドルのチーム料金では、小規模チームでも年間数百〜数千ドルの費用になります。

では、API開発チームにとって実用的なPostman代替ツールは何か？

短い答えは、単なる安価なAPIクライアントではなく、共同作業可能なAPIプラットフォームを求めるなら、Apidogが有力な選択肢です。

この記事では、Postmanのコストがチームに与える影響、代替ツールの選び方、そしてPostmanからApidogへ移行するための実践的な手順を整理します。

なぜPostmanがチームにとって高価に感じられるのか

Postmanに価値がないわけではありません。問題は、多くのチームが無料の共同作業機能を前提にワークフローを組んできたにもかかわらず、チーム利用では有料プランが必要になる点です。

ソロ開発者なら大きな問題ではないかもしれません。しかし、複数人でAPIを設計・実装・テスト・共有するチームでは、すぐにコストが積み上がります。

一般的に議論される月額ユーザーあたり19ドルで計算すると、次のようになります。

チームサイズ	月額費用	年間費用
2ユーザー	$38/month	$456/year
5ユーザー	$95/month	$1,140/year
10ユーザー	$190/month	$2,280/year
25ユーザー	$475/month	$5,700/year
50ユーザー	$950/month	$11,400/year

これは、上位機能、セキュリティ要件、SSO、ガバナンス、高度な監視、エンタープライズ要件を考慮する前の話です。

資金力のあるエンジニアリング組織なら許容できるかもしれません。しかし、スタートアップ、代理店、QAチーム、サイドプロジェクト、オープンソースプロジェクトでは、「APIリクエストを共有するためだけに高い固定費を払っている」と感じやすくなります。

まず決めるべきこと：無料クライアントで十分か、完全な置き換えが必要か

Postman代替ツールを選ぶ前に、まずチームが何を置き換えたいのかを明確にします。

無料のPostman代替ツールが、必ずしもチームにとって最適なPostmanの代替ツールとは限りません。

一部のツールはリクエスト送信には優れていますが、ドキュメント管理には弱いです。別のツールはローカルやGitベースのワークフローには向いていますが、QAやPMとの共同作業には不向きです。安価でも、モックサーバー、パフォーマンステスト、ロール管理、E2Eテスト自動化が不足している場合があります。

選定前に、次の表でチームの状況を整理してください。

あなたの状況	適した代替ツール
無料でAPIリクエストを送信したいソロ開発者	軽量APIクライアントまたはVS Code拡張機能
2〜5人のスタートアップ	低コストの共同作業APIプラットフォーム
オープンソースプロジェクト	ローカル優先またはGitベースのツール
QAが重要なプロダクトチーム	APIテスト、結合テスト、ワークフローテスト対応ツール
多数のクライアントAPIを管理する代理店	ワークスペース、環境、ドキュメント、インポート/エクスポート対応ツール
規制要件のあるチーム	ローカルストレージ、アクセス制御、シークレット管理、監査性
プラットフォームエンジニアリングチーム	API設計、ドキュメント、モック、テスト、CI/CD、ガバナンス対応プラットフォーム

リクエスト共有だけが目的なら、軽量な無料クライアントで十分かもしれません。

一方で、共同作業、テスト、ドキュメント、モック、環境、認証、認可、APIセキュリティワークフローまで必要なら、より完全なAPIプラットフォームが必要です。

総合的な代替候補：共同作業するAPIチーム向けのApidog

共同作業コストを理由にPostmanから移行するなら、Apidogは最初に検討すべき実用的な候補です。

Apidogは単なるリクエスト送信ツールではありません。仕様駆動型のAPI開発プラットフォームとして、Postmanのコレクション、ドキュメント、モック、テスト、環境に分散していた作業を1つのワークフローにまとめられます。

Apidogが向いているチーム

次のような要件がある場合、Apidogは有力な選択肢になります。

共有APIワークスペースが必要
Postmanコレクションをインポートしたい
APIテストと結合テストを管理したい
環境変数をチームで扱いたい
モックサーバーを使いたい
自動テスト生成を使いたい
ワークフローテストを実行したい
パフォーマンステストやロードテストも扱いたい
APIドキュメントを共有したい
認証・認可テストを実行したい
インポート、エクスポート、フォーマット変換が必要

Postman代替を探すチームの多くは、APIプロセスをゼロから作り直したいわけではありません。既存コレクションを移行し、テストを継続し、ドキュメントを共有し、月額コストを抑えながら共同作業を続けたいのです。

Apidogが単なる安価なPostmanクローンではない理由

軽量クライアントでも GET リクエストは送信できます。それだけなら十分な場面もあります。

しかし、チームでは次のような実務上の問いが発生します。

PMはAPIドキュメントを読めるか？
QAは回帰テストフローを実行できるか？
開発者はステージング環境と本番環境を安全に共有できるか？
バックエンドが未完成でもフロントエンドはモックで開発できるか？
CIパイプラインでAPIテストを実行できるか？
認証・認可の挙動を検証できるか？
リリース前にパフォーマンステストを実行できるか？

Apidogは、こうしたチーム向けワークフローを前提に設計されています。そのため、「Postmanがチームには高すぎる。代替ツールは何がよいか？」という問いに対して、APIプラットフォームとしての置き換えを求めるなら、強い候補になります。

移行プレイブック：PostmanからApidogへ移行する手順

Postman代替ツールの比較で見落とされがちなのが、実際の移行手順です。サブスクリプション費用だけでなく、切り替えコストも重要です。

Postmanからのインポート - Apidogドキュメント

以下の手順で進めると、チームの混乱を抑えながら移行できます。

1. Postmanで実際に使っているものを棚卸しする

まず、移行対象を一覧化します。

コレクション
フォルダー
リクエスト
環境
グローバル変数
プリリクエストスクリプト
テストスクリプト
モックサーバー
モニター
ドキュメント
API例
認証設定
CI/CD利用状況
共有ワークスペース
チーム権限

すべてを盲目的に移行しないでください。古いコレクションが多く、実際には20%だけを移行すれば十分なケースもあります。

2. Postmanコレクションをエクスポートする

Postmanで、アクティブなコレクションをJSONとしてエクスポートします。

おすすめの進め方は次の通りです。

製品領域ごとに1つずつエクスポートする
元のフォルダー構造を維持する
billing-api.postman_collection.json のように明確なファイル名にする
一時的な移行リポジトリに保存する
検証担当としてコレクション所有者を割り当てる

3. 環境をエクスポートする

コレクションだけでは不十分です。環境変数も移行対象になります。

次のような環境をエクスポートします。

ローカル
開発
ステージング
本番
デモ
QA

エクスポート後は、Gitにコミットする前にシークレットを必ず削除してください。

確認すべき変数の例です。

base_url
auth_token
client_id
client_secret
api_key
tenant_id
user_id
refresh_token

このタイミングで命名も整理します。たとえば、チームの一部が staging_url を使い、別のメンバーが baseUrl を使っているなら、移行中に統一してください。

4. PostmanコレクションをApidogにインポートする

Apidogにインポートしたら、次の項目を確認します。

リクエスト
フォルダー構造
環境
認証設定
テストロジック
例
ドキュメントフィールド

移行直後は、重要なAPIから順に手動で実行し、レスポンスとテスト結果が期待通りかを確認します。

5. スクリプトとテストを検証する

Postmanスクリプトは、常に完全に移行できるとは限りません。特に次の項目を確認してください。

プリリクエストスクリプト
テストアサーション
動的変数
トークン更新ロジック
リクエストチェーン
コレクションランナー
環境変数の更新処理

Postmanスタイルのアサーション例です。

pm.test("returns 200", function () {
  pm.response.to.have.status(200);
});

pm.test("response has user id", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("id");
});

移行後は、主要なテストケースを優先して再実行し、失敗したアサーションを修正します。

6. モニターとスケジュールされたテストを置き換える

Postmanモニターを使っている場合、まず用途を分類します。

稼働時間チェック
認証済みAPIチェック
回帰テスト
本番環境スモークテスト
SLA監視

そのうえで、新しいプラットフォーム、CI/CDパイプライン、または監視ツールで再構築するかを決めます。

Apidogへ移行する場合は、テストを次のように分離すると保守しやすくなります。

機能APIテスト
結合テスト
ワークフローテスト
パフォーマンステスト
ロードテスト

7. モックを再構築する

モックサーバーは、フロントエンド開発で重要です。Postmanのモックを使っていた場合、次の情報を洗い出します。

エンドポイントパス
HTTPメソッド
レスポンス例
ステータスコード
遅延動作
エラーレスポンス
認証の前提

その後、Apidogなどの代替ツールで再作成します。モックを先に整備しておくと、移行中でもフロントエンドとバックエンドが独立して開発を続けられます。

8. ドキュメントを移行する

PostmanコレクションからAPIドキュメントを生成していた場合、移行後のドキュメント配置も決める必要があります。

確認すべきポイントは次の通りです。

誰がドキュメントを読むのか？
公開用か、社内用か？
API例はテストと同期する必要があるか？
フロントエンド開発者が実装中に参照するか？
外部パートナーにアクセス権が必要か？

APIドキュメントは、単なる説明ではなく、開発・QA・外部連携の基盤になります。移行時に運用ルールも合わせて決めてください。

9. CI/CDパイプラインを更新する

リポジトリ内で、次の文字列を検索します。

newman
postman
postman_collection
postman_environment

Newmanや他のランナーでPostmanコレクションをCI実行している場合、代替手段を用意します。

選択肢は次の通りです。

新しいプラットフォームのCLIまたはテストランナーを使う
テストをコードベースのAPIテストに変換する
移行中はエクスポート済みコレクションを一時的に保持する
主要フローを結合テストとして再構築する

新しいワークフローでCIが安定してからPostmanを解約してください。

10. チームをオンボーディングし、古いコレクションを凍結する

最後はプロセス設計です。移行期限を設定し、チーム全体で新しい運用に切り替えます。

新しいAPIリクエストは新しいツールに登録する
古いPostmanコレクションは読み取り専用にする
所有者がインポート済みコレクションを検証する
QAがテストカバレッジを承認する
開発者がオンボーディングドキュメントを更新する

期限を決めないと、チームはPostmanと新ツールの間で分断され、移行が長引きます。

結論：コストだけでなく、移行後のワークフローで選ぶ

PostmanはAPIテストツールの代表的な存在ですが、チームで使う場合は料金が大きな判断材料になります。無料プランやチーム機能の制限により、共同作業を続けるには有料プランが必要になるケースがあります。

Apidogは、チームがPostmanから移行する際の現実的な選択肢です。

無料プランでチーム共同作業を始められる

小規模チームが支払い前提にならずにAPI開発を進められます。
有料プランのコストを抑えやすい

チーム規模が大きくなるほど、ユーザー単価の差が効いてきます。
設計、テスト、モック、ドキュメントを1つの流れで扱える

単なるAPIクライアントではなく、API開発プラットフォームとして使えます。
Postmanコレクションをインポートできる

既存資産を活かして移行できます。
チーム運用に必要な管理機能を検討できる

SSO、SCIM、RBACなど、組織利用で必要になる機能も選定時に確認できます。

実践的な切り替え手順はシンプルです。Postmanコレクションを棚卸しし、必要なものだけをエクスポートし、Apidogにインポートし、環境とテストを検証し、チームを新しいワークフローへ移行します。

よくある質問：Postmanの料金と代替ツール

Postmanはまだ無料ですか？

Postmanには無料プランがあります。ただし、チームでの共同作業や高度な機能を使う場合は、有料プランが必要になることがあります。利用前に最新のPostman料金ページで制限を確認してください。

なぜPostmanは高いと感じられるのですか？

Postmanは無料の開発者向けAPIクライアントから、監視、ガバナンス、コラボレーション、エンタープライズ機能を含むAPIプラットフォームへ拡張してきました。その結果、単にAPIリクエストを共有したい小規模チームにとっては、必要な機能に対するコストが高く感じられる場合があります。

Postmanの無料代替ツールとして何を検討すべきですか？

チームでAPI設計、テスト、モック、ドキュメント作成まで扱いたいなら、Apidogを検討できます。Apidogでは、API設計、APIテスト、APIモック、APIドキュメント作成を1つのプラットフォームで扱えます。InsomniaやBrunoも無料代替として候補になりますが、共同作業要件に合うかを確認してください。

10人チームの場合、Postmanはいくらですか？

月額ユーザーあたり19ドルで計算すると、10人チームでは月額190ドル、年間2,280ドルです。実際の費用は契約プラン、請求条件、必要な機能によって変わるため、最新の料金ページで確認してください。

Apidogをチームで無料利用できますか？

Apidogには無料プランがあります。小規模チームでAPI設計、テスト、モック、環境、ドキュメント機能を試す場合に利用できます。最新の利用条件は公式サイトで確認してください。

PostmanからApidogへ移行する方法は？

PostmanからApidogへの移行は、基本的に次の手順で進めます。

PostmanコレクションをJSON形式でエクスポートする
Apidogにインポートする
環境変数と認証設定を確認する
スクリプトとテストを検証する
チームを招待して新しい運用に切り替える

ApidogはPostmanコレクションをサポートしていますか？

はい。ApidogはPostmanコレクションのインポートに対応しています。移行後は、リクエスト、環境、変数、認証設定、テストなどを確認し、重要なAPIから順に検証してください。

PostmanにはないApidogの機能は何ですか？

Apidogは、API設計、テスト、モック、ドキュメント作成を1つのインターフェースで扱える点が特徴です。また、HTTP、GraphQL、WebSocket、gRPC、SSEなど複数のプロトコルを扱えるワークフローも提供しています。必要な機能が現在のPostman利用範囲と合うかを比較してください。

Apidogはエンタープライズ対応ですか？

はい。Apidogは、SSO、SCIM、監査ログ、高度なRBACなど、組織利用に必要な機能を提供しています。また、オンプレミスデプロイメントやカスタムガバナンスも検討できます。

開発者向けAI画像検出APIおすすめ2026年版

Akira — Mon, 08 Jun 2026 06:37:02 +0000

AI画像生成ツールは急速に進化しました。実在しない人物の写真、撮影されたことのない製品ショット、起こらなかった出来事の「スクリーンショット」まで、数秒で生成されます。マーケットプレイス、出会い系アプリ、ニュースプラットフォーム、本人確認フロー、ユーザー生成コンテンツフィードを運営しているなら、最終的には「この画像は機械によって作られたものか？」をプログラムで判定する必要があります。

Apidogを今すぐ試す

AI画像検出APIは、この問いに対して確率スコアや生成モデルの推定を返します。ただし、この分野はまだ混沌としています。実際のAPIを持たないWebツールもあれば、営業経由でしか使えないエンタープライズ製品もあります。一方で、オープンサインアップ、明確なRESTドキュメント、開発者向けの無料枠を備えたAPIも存在します。

要約

モデル帰属と明確なRESTドキュメントを重視するなら、一般的な選択肢としては Sightengine と Hive Moderation が有力です。シンプルな同期エンドポイントを使いたい場合は AI or Not も候補になります。

ディープフェイク、特に顔のなりすましが主なリスクなら Reality Defender を優先してください。公開無料枠があります。

OpenAIのDALL-E 3分類器 は研究アクセス向けであり、一般的な開発者APIではありません。

重要なのは、どの検出器も決定的ではないことです。スコアは「最終判断」ではなく「信号」として扱い、しきい値、レビュー導線、監査ログと組み合わせて実装してください。

AI画像検出APIを評価する方法

ベンダー比較の前に、まず自分のプロダクトで何を守りたいのかを定義します。ベンチマーク上は高精度でも、自社トラフィックでは期待通りに動かないことがあります。

精度は自社データで検証する

ベンダーが提示する精度値は、そのテストセットに依存します。

確認すべき点は次の通りです。

どの生成器で学習・評価されているか
Midjourney、Stable Diffusion、DALL-E、Flux、Firefly、Imagenなどをどこまでカバーしているか
リサイズ、再圧縮、スクリーンショット、トリミング後の画像でも性能が出るか
最新モデルに追従しているか
自社の実画像に近い条件で検証できるか

実装前に、少なくとも以下のような評価セットを作ると判断しやすくなります。

dataset/
  real/
    marketplace_photo_001.jpg
    user_profile_001.jpg
  ai_generated/
    midjourney_001.jpg
    dalle_001.jpg
    stable_diffusion_001.jpg
  edited/
    recompressed_001.jpg
    cropped_001.jpg
    screenshot_001.jpg

APIの精度は、この評価セットで比較してください。

誤検出（False Positive）のコストを設計に入れる

AI画像検出では、主に2種類の失敗があります。

False Negative: AI生成画像を見逃す
False Positive: 本物の画像をAI生成と誤判定する

多くのプロダクトでは、False Positiveの方が大きな問題になります。本物のユーザーを不正扱いするためです。

そのため、実装では「即ブロック」ではなく、スコア帯ごとに処理を分けるのが現実的です。

function decideAction(score) {
  if (score >= 0.9) {
    return "reject_or_hold";
  }

  if (score >= 0.6) {
    return "manual_review";
  }

  return "allow";
}

しきい値は固定せず、実トラフィックとレビュー結果を見ながら調整してください。

レイテンシーとスループットを測る

画像検出をアップロードフローに同期的に入れる場合、APIの応答時間はUXに直結します。

確認すべき項目は次の通りです。

自社リージョンからの実測レイテンシー
画像サイズごとの応答時間
同時リクエスト時の挙動
無料枠・有料枠のレート制限
タイムアウト時のフォールバック

同期処理にする場合は、最低限タイムアウトを設定します。

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);

try {
  const response = await fetch(process.env.AI_IMAGE_DETECTOR_ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AI_IMAGE_DETECTOR_API_KEY}`,
    },
    body: formData,
    signal: controller.signal,
  });

  const result = await response.json();
  console.log(result);
} finally {
  clearTimeout(timeout);
}

アップロード体験を止めたくない場合は、非同期ジョブにして後続処理でレビュー・制限をかける設計も検討してください。

モデルカバレッジを確認する

「AI生成」といっても、生成器ごとに特徴は異なります。検出器は特定の生成器ファミリーに対して訓練されています。

確認すべき生成器の例は次の通りです。

Midjourney
Stable Diffusion
DALL-E
Flux
Firefly
Google Imagen
その他の新しい生成モデル

画像がAI生成かどうかだけでなく、どのモデルで作られた可能性が高いかを知りたい場合は、生成器ごとの信頼度スコアを返すAPIを選んでください。

ディープフェイクは別枠で考える

完全に合成された画像の検出と、本物の写真に加工された顔を検出することは別問題です。

本人確認やなりすまし対策が目的なら、一般的なAI画像検出APIよりも、ディープフェイク検出に強いAPIを優先してください。

料金モデルを実リクエスト数で試算する

ベンダーごとに課金単位が異なります。

画像ごと
操作ごと
クレジットごと
月額ティア + 超過料金
エンタープライズ見積もり

注意点は、1回のアップロードで複数チェックが走る場合です。

1アップロード = AI画像検出 + NSFWチェック + 顔検出
月間100,000アップロード
=> 実際の課金対象は300,000操作になる可能性

料金表は、API呼び出し単価ではなく、実際の処理フローに合わせて見積もってください。

データプライバシーとデータレジデンシーを確認する

ユーザー画像を第三者に送信するため、データ処理条件は必ず確認してください。

確認すべき質問は次の通りです。

画像は保存されるのか
保存期間はどれくらいか
学習データに使われるのか
削除リクエストは可能か
オンプレミスまたは地域内デプロイは可能か
規制産業で利用できる条件を満たすか

検出の限界については、AI画像検出が失敗する理由も参考になります。

Hive Moderation

Hive（Hive AI / Hive Moderation）は、コンテンツモデレーション分野で広く使われているベンダーです。AI生成コンテンツやディープフェイクの検出に加えて、ビジュアルモデレーション、テキスト、オーディオ製品も提供しています。

検出するもの

HiveのAI生成コンテンツ分類器は、画像がAI生成かどうかの信頼度スコアを返します。また、どの生成エンジンで作られた可能性があるかも返します。

製品ラインナップは、画像、ビデオ、オーディオをカバーし、ディープフェイク検出も含まれます。

アクセス方法

Hiveはセルフサービス開発者プランを提供しています。サインアップ後、支払い方法を追加すると、テスト用の無料スタータークレジットを利用できます。

セルフサービスV3 APIはすぐに利用でき、V3 APIキーを作成して呼び出せます。大容量トラフィックでは、カスタムレート制限と価格設定のためにエンタープライズプランへ移行します。オンプレミスデプロイメントもエンタープライズ顧客向けに提供されています。

現在の料金は、Hiveの料金ページで確認してください。

長所

成熟したプロダクトで、セルフサービスティアがある
バイナリ判定だけでなく、生成元の推定も返す
画像、ビデオ、オーディオ、モデレーションを1ベンダーで扱える
オンプレミスオプションがある

短所

デフォルトのセルフサービスレート制限は控えめ
大規模利用ではエンタープライズ相談が必要
上位ティアの総コストは事前に見えにくい
精度は生成器と画像品質に依存する

Sightengine

Sightengineは、コンテンツモデレーションと画像解析のAPI企業です。AI生成画像検出についても開発者向けドキュメントが整っており、実装しやすい選択肢です。

検出するもの

Sightengineは、画像がAIモデルによって生成されたかどうかを判定し、生成器ごとの信頼度スコアを返します。

ドキュメントでは、Stable Diffusion、Midjourney、DALL-E / GPT画像出力、Flux、Firefly、Googleの画像モデル、Seedreamなどのカバー範囲が説明されています。

AI生成ビデオ検出とディープフェイク検出も、個別のチェックとして提供されています。

アクセス方法

オープンサインアップに対応しています。Sightengineには、評価目的で期間制限なく使える無料プランがあります。ただし、月間・日間の操作回数には上限があります。

有料ティアでは制限が引き上げられ、超過料金も設定されています。注意点は、使用量が「操作」として計測されることです。AI生成画像検出のような高度なチェックは、標準的なモデレーションよりも1呼び出しあたりの操作コストが高くなる場合があります。

現在の料金と操作コストは、Sightengineの料金ページで確認してください。

長所

開発者向けドキュメントが整っている
Python、PHP、Nodeの公式SDKがある
生成器ごとのスコアを返す
時間制限なしの無料枠がある
AI画像、AIビデオ、ディープフェイクを同じベンダーで扱える

短所

「操作」単位の課金を実コストに換算する必要がある
高度な検出は1操作とは限らない
新しい生成器への追従には再トレーニングが必要

AI or Not

AI or Notは、AI生成メディアや操作されたメディアの検出に特化したスタートアップです。広範なモデレーション製品の一部ではなく、検出そのものが中心機能です。

検出するもの

AI or Notは、画像がAI生成かどうかを分類し、MidjourneyやDALL-Eなどの生成器固有の信号も返します。

ディープフェイク検出、NSFW、画像品質信号なども含まれます。同社は精度数値を公開していますが、他の検出器と同様に、自社データで検証してください。

アクセス方法

オープンサインアップに対応しています。アカウントを作成し、APIキーを取得して、BearerトークンでAPIを呼び出します。

Webサイト上では無料の単一画像チェックを提供しており、一括利用や商用利用向けの有料APIもあります。

現在のプランと制限は、AI or Not APIドキュメントで確認してください。

長所

同期エンドポイントがシンプル
1リクエストでレポートを取得できる
検出が主要製品
生成器帰属、ディープフェイク、品質信号をまとめて返す
評価用の無料導線がある

短所

既存の大手モデレーションベンダーより小規模
長期的な依存関係は慎重に評価する必要がある
公開されている料金情報は限定的

Reality Defender

Reality Defenderは、企業や政府向けにディープフェイク検出を提供してきた企業です。2025年に公開開発者APIと無料枠を開放し、2026年には個人開発者もアクセスできるようになりました。

検出するもの

Reality Defenderの強みはディープフェイク検出です。顔の操作、なりすまし、合成メディアの検出に重点があります。

現在は画像とオーディオの検出をサポートしており、ビデオも追加予定として示されています。一般的なAIアート検出よりも、本人確認や顔操作のリスクが大きい場合に向いています。

アクセス方法

無料枠付きの公開APIです。Reality DefenderプラットフォームでRealAPIアカウントを作成し、APIキーを生成してリクエストを認証します。

無料枠では、評価用に少量の月間スキャンが提供されます。有料プランでは制限が引き上げられます。

現在のティアは、Reality DefenderのAPIページで確認してください。

長所

ディープフェイク検出に特化
企業実績がある
公開無料枠があり、営業商談なしで評価できる
Python、TypeScript、Go、Rust、Java、直接HTTPSに対応
マルチモデル検出を採用

短所

一般的なAIアート検出では、より広範なベンダーの方が生成器カバレッジが広い可能性がある
無料枠は評価向けで、本番トラフィックには少ない

OpenAIのDALL-E 3検出分類器

OpenAIは、画像が自社のDALL-E 3モデルから生成されたものかどうかを予測する分類器を構築しています。ただし、これは一般開発者がすぐに使える汎用APIではありません。

検出するもの

DALL-E検出分類器は、画像がDALL-E 3で生成された可能性を推定する二値分類器です。真偽の結果と連続スコアを返します。

対象はDALL-E 3に限定されます。Midjourney、Stable Diffusion、その他の生成器は対象外です。

OpenAIは、DALL-E 3画像に対する高い内部精度と低い誤検出率を報告していますが、これはOpenAI自身のモデルに関する内部数値です。

アクセス方法

アクセスはOpenAIの研究者アクセスプログラムに制限されています。研究機関や研究志向のジャーナリズム非営利団体が、分類器を評価するためにAPIクレジットを申請する形式です。

オープンサインアップの開発者APIではないため、これを前提に本番機能を設計すべきではありません。

OpenAIは、2026年5月のコンテンツ来歴の推進に関する投稿で、C2PA運営委員会への参加や画像出力へのSynthID透かしの追加について説明しています。

それでも重要な理由

OpenAIの方向性は、業界が「検出単独」から「来歴メタデータ + 透かし技術」へ向かっていることを示しています。

長期的に設計するなら、分類器の確率スコアだけでなく、C2PAコンテンツクレデンシャルやSynthIDのような信号も読み取れるようにしておくべきです。

長所

DALL-E 3画像に対して高精度が報告されている
二値判定と連続スコアを返す

短所

研究アクセスのみ
オープンサインアップがない
DALL-E 3に限定される
本番機能の前提にはできない

Illuminarty

Illuminartyは、消費者向けWebツールと開発者向けAPIの両方を提供する検出サービスです。公開料金体系を持つ、比較的手頃な選択肢です。

検出するもの

Illuminartyは、画像がAI生成かどうかを確認し、どの生成器が使われた可能性が高いかを推定します。

また、局所検出を提供し、画像のどの領域が合成に見えるかを示します。画像全体ではなく、一部編集が疑われる場合に有用です。

アクセス方法

オープンサインアップに対応しています。基本的な画像・テキスト分類向けの無料プランと、モデル識別、局所検出、高い日次リクエスト制限を追加する有料月額ティアがあります。

プランは変更される可能性があるため、契約前にIlluminartyサイトで現在のティアと制限を確認してください。

長所

公開された予測しやすい料金体系
局所検出で合成が疑われる領域を確認できる
基本分類向けの無料プランがある

短所

大手モデレーションベンダーより小規模
SLAや長期サポートは事前に確認が必要
生成器カバレッジは自社トラフィックで検証すべき

Hugging Face ホスト型分類器モデル

Hugging Faceは検出企業ではなくモデルハブです。ただし、ホスト型推論でオープンソースのAI画像検出モデルを実行できるため、コントロールや低コストを重視するチームには現実的な選択肢になります。

検出するもの

検出内容は、選択するモデルに完全に依存します。

Hugging Face Hubには、SigLIPやVision Transformersなどのアーキテクチャを使い、画像をAI生成または人間作成として分類するコミュニティモデルがあります。

ただし、各モデルには独自の訓練データ、生成器カバレッジ、精度プロファイルがあります。単一ベンダーによる保証はありません。

アクセス方法

Hugging Faceアカウントとアクセストークンを作成します。

軽い利用ではサーバーレス推論APIを呼び出せます。安定した本番トラフィックには、専用の推論エンドポイントをデプロイできます。モデル重みをダウンロードして自己ホストすることも可能です。

モデルはhuggingface.coで検索できます。

長所

モデルを選択、検査、微調整、自己ホストできる
大規模利用では低コストになる可能性がある
ベンダーロックインが少ない
オープンモデルを使える

短所

ベンダーによる精度保証やサポートはない
モデル選択、評価、更新、稼働率管理は自社責任
コミュニティモデルは最新生成器に追従していない場合がある
ターンキーAPIよりエンジニアリング作業が多い

この方式を選ぶ場合は、独自のAI画像検出器APIを構築するで、モデルをAPIサービスとしてラップする方法を確認できます。

実装時の基本パターン

どのベンダーを選ぶ場合でも、基本的な実装フローは同じです。

1. ユーザーが画像をアップロード
2. 画像を一時保存
3. AI画像検出APIへ送信
4. スコアとメタデータを保存
5. しきい値に応じて allow / review / reject を決定
6. 境界線のケースは人間レビューへ送る

レスポンスは、後からしきい値を再評価できるように保存しておくと便利です。

{
  "image_id": "img_123",
  "provider": "example_detector",
  "ai_score": 0.82,
  "model_scores": {
    "midjourney": 0.64,
    "stable_diffusion": 0.21,
    "dalle": 0.12
  },
  "decision": "manual_review",
  "created_at": "2026-06-08T10:00:00Z"
}

最初から自動拒否に寄せるのではなく、レビュー結果を蓄積してしきい値を調整するのが安全です。

比較表

プロバイダー	オープンサインアップ	検出するもの	APIスタイル	生成元帰属	ディープフェイクサポート	無料枠	料金モデル
Hive Moderation	はい、セルフサービス	AI画像、ビデオ、オーディオ	REST	はい、生成元を予測	はい	サインアップ時にスタータークレジット	セルフサービスとエンタープライズ見積もり
Sightengine	はい	AI画像、ビデオ、ディープフェイク	RESTとSDK（Python、PHP、Node）	はい、生成器ごとのスコア	はい	はい、期間制限なし	月額ティア、操作数で課金
AI or Not	はい	AI画像、オーディオ、ディープフェイク	REST、同期エンドポイント	はい、生成器ごと	はい	無料の単一画像チェック	一括および商用利用向け有料API
Reality Defender	はい、公開API	ディープフェイク、AI画像、オーディオ	RESTとSDK（Python、TS、Go、Rust、Java）	検出に特化	はい、中核機能	はい、少量の月間割り当て	無料枠と有料プラン
OpenAI DALL-E 3分類器	いいえ、研究アクセスのみ	DALL-E 3画像のみ	REST	いいえ、DALL-E 3に限定	いいえ	研究クレジットのみ	研究者アクセスプログラム
Illuminarty	はい	AI画像、局所領域	REST	はい、可能性のあるモデル	限定的	はい、基本分類	公開されている月額ティア
Hugging Face ホスト型モデル	はい（HFアカウント）	選択したモデルによる	REST推論	モデルによる	モデルによる	サーバーレスの無料利用、制限あり	利用ごとまたは専用エンドポイント

ここにあるすべてのオプションの精度は条件付きとして扱ってください。いずれも決定的な認証器ではありません。

結論

AI画像検出は有用ですが、魔法ではありません。最終判断ではなく、リスク判定システムの1つの信号として使ってください。

オープンサインアップと生成元帰属を重視するなら、Sightengine または Hive Moderation から始める
1回の呼び出しで完結する同期エンドポイントが必要なら、AI or Not を試す
ディープフェイクや顔の操作が主なリスクなら、Reality Defender を優先する
OpenAIのDALL-E 3分類器 は研究アクセスのみなので、本番機能の前提にしない
局所検出と低コストを重視するなら Illuminarty を検討する
自社でモデル運用できるなら、Hugging Face のホスト型モデルまたは自己ホストも選択肢になる
どのAPIも決定的ではないため、自社トラフィックで検証し、境界線のスコアは人間レビューへ回す

最も信頼できる選び方は、実際にテストすることです。各プロバイダーのエンドポイントをApidogに取り込み、実画像を送信し、JSONレスポンスを確認し、自社リージョンからのレイテンシーを測定してから本番実装に進めてください。

コーディングエージェントへのプロンプトをやめて、自動プロンプトループを構築する

Akira — Mon, 08 Jun 2026 04:08:40 +0000

コーディングエージェントに「次のプロンプト」を投げ続けるのではなく、エージェントが自分で修正を繰り返せるループを設計しましょう。実装、実行、検証、失敗のフィードバック、再実行までを自動化すると、AIはチャット相手ではなく、検証ゲートの中で動くワーカーになります。AIコーディングエージェントを実務で活かすには、プロンプトの技巧よりも、ループとテストの設計が重要です。

今すぐApidogを試す

TL;DR

コーディングエージェントループとは、次の処理を自動で繰り返す制御構造です。

エージェントがコードを変更する
テスト、ビルド、型チェック、APIテストを実行する
決定論的なゲートで合否を判定する
失敗内容を次の入力としてエージェントに返す
成功するか、上限に達するまで繰り返す

重要なのはエージェントそのものではなく、検証ゲートです。

「問題なさそう。もう一度試して」のような曖昧なフィードバックでは、エージェントは迷走し、完了を幻覚します。一方で、失敗したテスト、スキーマ不一致、契約違反、ステータスコード差分のような明確なシグナルを返すと、ループは収束します。

APIやバックエンド開発では、自動テストスイートと契約チェックがそのゲートになります。だからこそ、APIテストはエージェントワークフローの最後に追加するものではなく、中心に置くべきものです。

プロンプトからループ設計へ

多くの開発者は、チャットボックス経由でAIコーディングを始めます。

「この関数を書いて」

「このエラーを直して」

「このAPIを実装して」

小さな関数や説明ならこれで十分です。しかし、実際の開発タスクは通常、1回の回答では終わりません。テストが落ち、型が合わず、エッジケースが漏れ、仕様と実装がずれます。

手動プロンプトの問題は、あなた自身がループになっていることです。

出力を読む
バグを見つける
エラーをコピーする
次の指示を書く
もう一度待つ

エージェントは数秒でコードを書けますが、人間がコンテキストを切り替え、ログを読み、次のプロンプトを考えている間は停止しています。高速なシステムの中で、最も遅い部分が人間になります。

ループを設計すると、この構造が変わります。

エージェントがコードを書く。

スクリプトがテストを実行する。

結果をキャプチャする。

失敗したら、その失敗を次の入力として返す。

成功したら停止する。

内部ループに人間は不要です。人間は、タスクの定義、最終レビュー、失敗時のエスカレーションだけを担当します。

Anthropicの効果的なエージェントの構築でも、価値は単一の賢いプロンプトではなく、モデルの周囲に構築する環境から生まれると説明されています。

問いを変えましょう。

「エージェントに何を言うべきか？」ではなく、

「エージェント自身に次の入力を与えるループをどう設計するか？」です。

コーディングエージェントループの構成要素

実装レベルで見ると、コーディングエージェントループは5つの部品で構成できます。

タスク仕様

完了条件を明確に書きます。

「動くようにする」では不十分です。

例: POST /orders は作成された注文を含む 201 を返し、レスポンスボディはスキーマに一致し、必須フィールド不足は 422 で拒否する。
エージェント

モデルとツールです。ファイルの読み書き、シェルコマンドの実行、コード編集などを行います。
アクションステップ

エージェントが変更を加え、何かがそれを実行します。テスト、ビルド、型チェック、APIリクエストなどです。
検証ゲート

合格または不合格を、具体的な理由付きで返す決定論的なチェックです。ここがループのステアリングホイールです。
終了条件

いつ止めるかを決めます。ゲートが合格したとき、最大反復回数に達したとき、またはコスト上限を超えたときです。出口のないループはワークフローではなく暴走です。

擬似コードにすると、基本形はこうなります。

task = load_spec("orders-endpoint.md")
last_result = None

for attempt in range(MAX_ITERATIONS):
    agent.run(task, feedback=last_result)   # 生成・修正
    result = run_verification()             # 実行 + ゲート判定

    if result.passed:
        break                               # 成功して終了

    last_result = result.failures           # 失敗を次の入力にする
else:
    escalate_to_human(last_result)          # 上限到達で人間に渡す

エージェントが生成し、ゲートが判断し、失敗が次のプロンプトになります。これがループの本質です。

オンラインで「Ralph」テクニックとして共有されているパターンも、基本的には MAX_ITERATIONS を高めに設定し、仕様と検証を厳密にしたものです。エージェントハーネスアーキテクチャの観点で見ると、このループは最小構成のハーネスです。

ワンショットプロンプトが限界に達する理由

単一のプロンプトは、次のどちらかを前提にしています。

モデルが初回で正しく実装する
人間がモデルのミスを見つけて修正指示を出す

どちらも大規模な開発では破綻します。

モデルは、もっともらしいコードを生成するのは得意です。しかし、そのコードが本当に正しいかを判断するのは苦手です。

たとえば、エンドポイントはコンパイルでき、簡単なリクエストにも応答するかもしれません。しかし、次のような問題が残ることがあります。

必須フィールド不足で 422 ではなく 500 を返す
レスポンスの total が数値ではなく文字列になる
認証が必要なエンドポイントで未認証アクセスを許可する
OpenAPI仕様と実装がずれる
エッジケースだけで誤ったステータスコードを返す

チャット上では、モデルは「完了しました」と自信を持って言うかもしれません。しかし、モデルの自信は合否判定ではありません。

ループは、モデルに自己採点させません。

エージェントは「完了」と宣言できません。

ゲートだけが完了を宣言できます。

テストが赤なら未完了。

スキーマ検証が落ちるなら未完了。

契約違反があるなら未完了。

この構造にすると、次の入力は人間の感想ではなく、機械生成された失敗シグナルになります。

また、ループは並列化しやすいという利点もあります。手動プロンプトでは、人間が監視できる1つのエージェントが限界です。ループ化すれば、複数のエージェントを別々のタスクとゲートに対して同時に走らせられます。

これは、動的で並行的なエージェントワークフローで扱われる発想と同じです。入力速度を上げるのではなく、ループを増やしてスケールします。

検証ゲートがループの品質を決める

エージェントワークフローが失敗する主な理由は、モデルが弱いことではありません。フィードバックシグナルが弱いことです。

ゲートは各イテレーションで、エージェントに次のどちらかを返します。

合格。停止。
不合格。理由はこれ。

この「理由」の品質が、次の修正の品質を決めます。

良いフィードバック:

Expected 422 when customer_id is missing, but got 500.
Test: orders.validation.missing_customer_id
File: tests/orders_validation_test.py:42

悪いフィードバック:

何かがおかしいようです。確認してください。

前者なら、エージェントは特定の失敗を修正できます。後者では推測が始まり、コードをさらに悪化させることがあります。

決定論的なゲートは収束します。

曖昧なゲートは迷走します。

良いゲートには、次の性質が必要です。

バイナリで再現性がある

同じ入力なら同じ結果を返す。モデルの気分やレビュー担当者の感覚に依存しない。
失敗理由が具体的

テスト名、期待値、実際の値、差分、行番号、ステータスコードを返す。
エージェントが勝手に変更できない

エージェントがテストを書き換えて合格できるなら、ゲートではありません。テストと仕様は保護します。
高速に実行できる

20分かかるゲートは内部ループには向きません。短い反復には高速なチェックが必要です。

実際には、多くの成熟したコードベースにはすでにゲートがあります。

ユニットテスト
型チェッカー
リンター
コンパイラ
スキーマバリデーター
APIテスト
契約テスト

これらは、人間に「ここが間違っている」と伝えるために作られた決定論的なオラクルです。そして、それはそのままエージェントループに必要なシグナルになります。

まだ自動テストの層を整理していない場合は、自動テストとは何かを確認し、ループ化する前にゲートを整備してください。

APIおよびバックエンド開発では、テストスイートがループになる

APIエンドポイントをエージェントに実装させる場合、真実の源はモデルの要約ではありません。実際のエンドポイントの振る舞いです。

確認すべきものは明確です。

正しいステータスコードを返すか
レスポンスボディがJSONスキーマに一致するか
認証・認可が強制されるか
不正な入力を拒否するか
OpenAPI仕様と実装が一致するか
既存の契約を壊していないか

これらはすべて自動で検証できます。つまり、APIテストスイートは、そのままエージェントループの検証ゲートになります。

エンドポイント実装のループは、次のように設計できます。

エージェントがタスク仕様とOpenAPI定義を読む
エージェントが対象エンドポイントを実装または修正する
ハーネスが実行中のサービスに対してAPIテストを実行する
ステータスアサーション、JSONスキーマ検証、契約チェックを行う
失敗を構造化してエージェントに返す
テストがグリーンになるまで繰り返す
成功後に人間がレビューする

失敗フィードバックは、次のように具体的にします。

Expected 422 when customer_id is missing, but got 500.

Response field total is string, but schema expects number.

Endpoint /orders/{id} exists in OpenAPI spec but has no implementation.

このような機械生成のフィードバックがあると、エージェントは特定のギャップを修正できます。

スキーマファーストと契約テストは、エージェント時代にさらに重要になります。OpenAPI仕様が、エージェントとゲートの両方が読む共有の真実になるからです。

仕様とコードのずれは、もはや後で直すドキュメントの問題ではありません。即座に赤いゲートになります。

ここでApidogが役立ちます。Apidogは、API設計、スキーマ、モックサーバー、自動テストを1つのワークスペースで扱えるAPIプラットフォームです。

エージェントループをApidogのテストシナリオに接続すると、各イテレーションでスキーマ検証済みの合格・不合格を取得できます。また、モックサーバーを使えば、まだ構築されていない依存関係の代わりに安定したターゲットを用意できます。

すでにこの構成を使うチームでは、Apidog AIエージェントデバッガーのようなツールアクセスを接続し、エージェントが人間のテスターと同じようにエンドポイントを叩いて検査できるようにしています。

テストランナーを一から作るのではなく、視覚的にAPIゲートを構築したい場合は、Apidogをダウンロードしてください。

今日から最小限の自己修正APIループを作る

フレームワークは不要です。必要なのは、仕様、テストコマンド、簡単な接続コードです。

ステップ1：仕様をゲートの意図として書く

OpenAPIファイルに契約を書き、テストケースに振る舞いを書きます。

例:

paths:
  /orders:
    post:
      summary: Create an order
      responses:
        "201":
          description: Created order
        "422":
          description: Validation error

エージェントには、実装対象の仕様とテストを読ませます。ただし、後述するように、仕様やテスト自体は自由に編集させない方が安全です。

ステップ2：失敗時にゼロ以外の終了コードを返すコマンドを用意する

終了コードが正直であれば、ツールは何でも構いません。

pytest
Newman
Apidog CLIテストシナリオ
独自のAPIテストランナー

例:

# ゲートを単一コマンドとして実行
apidog run ./tests/orders-suite --reporter json > result.json

ループが必要とするのは、合否と出力だけです。

ステップ3：エージェントとゲートを接続する

最小構成は次のようになります。

import subprocess

MAX_ITERATIONS = 8
feedback = None

for attempt in range(MAX_ITERATIONS):
    run_agent(
        task="implement orders API per spec",
        feedback=feedback
    )

    gate = subprocess.run(
        [
            "apidog",
            "run",
            "./tests/orders-suite",
            "--reporter",
            "json"
        ],
        capture_output=True,
        text=True
    )

    if gate.returncode == 0:
        print(f"green on attempt {attempt + 1}")
        break

    feedback = parse_failures(gate.stdout)
else:
    print("8 attempts, still red; escalating to a human")

parse_failures() では、テスト出力からエージェントに返すべき失敗理由を抽出します。

例:

def parse_failures(output: str) -> str:
    # 実際にはJSONをパースして、失敗テスト名、期待値、実際の値を抽出する
    return f"""
The verification gate failed.

Use the following failures to fix the implementation.
Do not modify the tests or OpenAPI spec.

Failures:
{output}
"""

ステップ4：ゲートを保護する

エージェントが編集できるファイル範囲を制限します。

編集を許可するもの:

src/**
app/**
routes/**
controllers/**
services/**

編集させないもの:

openapi.yaml
tests/**
apidog-tests/**
contracts/**

エージェントがテストを書き換えて合格できるなら、進捗ではなく偽装を自動化しているだけです。

仕様は憲法です。エージェントは従うべきであり、勝手に変更すべきではありません。

ステップ5：コストと反復回数を制限する

必ず上限を設定します。

最大反復回数
最大実行時間
最大トークン使用量
最大コスト
失敗時のエスカレーション条件

収束しないループは、予算をすぐに消費します。トークン使用量を抑えたい場合は、エージェントのトークンコストを削減する方法も参考になります。

良いループを設計するための注意点

機能するループと、コストだけを消費するループには明確な違いがあります。

エージェント自身に採点させない

唯一のチェックが「完了しましたか？」なら、それはループではありません。余分な手順のあるチャットボットです。

ゲートは必ずエージェントの外部に置きます。

ゲートを粗くしすぎない

浅いテストが3つだけなら、エージェントはその3つだけを満たし、未カバーの部分にバグを残します。

ループの品質上限は、ゲートのカバレッジで決まります。

終了条件を忘れない

最大反復回数やコスト上限がないループは、解けないタスクで回り続けます。

必ず停止し、人間に渡す条件を定義してください。

遅いゲートを内部ループに使わない

15分かかる統合テストは、マージ前や夜間チェックには有効です。しかし、内部ループには遅すぎます。

おすすめは分離です。

内部ループ: 高速なAPIテスト、型チェック、限定的な契約テスト
マージ前: フル統合テスト、E2E、負荷テスト

外部依存関係はモックし、ループが不安定なサードパーティを待たないようにします。

仕様を勝手に変更させない

エージェントがバグのある実装に合わせてOpenAPI仕様を編集すると、契約テストは間違った理由でグリーンになります。

仕様は実装に合わせるものではなく、実装が仕様に従うべきです。

タスクを大きくしすぎない

「サービス全体を構築する」のような巨大タスクは収束しにくいです。

小さく分けます。

POST /orders
GET /orders/{id}
PATCH /orders/{id}/status
DELETE /orders/{id}

エンドポイント単位で仕様とゲートを持たせると、ループは完了しやすくなります。

これらのパターンは、Claude Code、Cursor、Codex、自作エージェントのどれを使っても同じです。詳細な配線パターンと失敗モードは、エージェントワークフローツールの配線でも扱っています。

これから重要になるスキル

「プロンプトをやめて、ループを始める」という考え方は、AI開発のスキルセットが変わっていることを示しています。

価値が高まるのは、プロンプトの言い回しではありません。次のようなループ設計のスキルです。

明確な仕様を書く
決定論的なゲートを作る
テスト出力を構造化する
終了条件を設定する
エージェントが触ってよい範囲を制限する
失敗時に人間へエスカレーションする

これはプロンプトエンジニアリングというより、システム設計です。テスト、契約、CIを重視してきたエンジニアほど、エージェントを安全に活用しやすくなります。

自動テストの価値も変わります。

以前の自動テストは、壊れたときに検知する保険のようなものでした。エージェントワークフローでは、テストはステアリングメカニズムになります。高速だが信頼できない生成器を、正しい方向に収束するシステムへ変えるための制御装置です。

すでに強力な自動テストカバレッジとクリーンな契約を持つチームは、すぐにエージェントを組み込めます。逆に、それがなければ、未テストのコードを高速に生成するだけになります。

要点

コーディングエージェントにプロンプトを出すのが上手くなるよりも、エージェントを動かすループと検証シグナルを設計する方が重要です。

エージェントは高速な生成器です。しかし、自分が正しいかを確実には判断できません。ループは、テスト、スキーマ、契約、型チェックのような決定論的ゲートを使って、その判断を外部から与えます。

APIを構築しているなら、ゲートはすでにあります。テストスイート、OpenAPIスキーマ、契約チェックです。

まずは小さく始めましょう。

厳密な仕様を1つ書く
高速なAPIテストスイートを1つ用意する
エージェントの編集範囲を制限する
失敗出力を次の入力として返す
最大反復回数を設定する
グリーンになったら人間がレビューする

赤いエンドポイントを、あなたが内部ループに介入せずに緑へ変えられるようになります。

ゲートを視覚的に作成し、スキーマ対応で、チーム間で共有したい場合は、ApidogがAPI設計、モック、自動テストを1つのワークスペースで提供します。ダウンロードして、テストをエージェントを駆動するゲートにしましょう。

最高のSolana API 2026年版：開発者、ウォレットアプリ、AIエージェント向け

Akira — Fri, 05 Jun 2026 14:11:43 +0000

Solanaは、高性能ブロックチェーンアプリケーションにとって最も重要なエコシステムの1つとなっています。

今すぐApidogを試す

その速度、低い取引手数料、そして成長する開発者エコシステムにより、Solanaはウォレットアプリ、DeFiプラットフォーム、取引システム、オンチェーンデータと直接対話するAIエージェントにとって有力な選択肢になっています。

ただし、Solana上で実用的なアプリケーションを構築するには、スマートコントラクトだけでは不十分です。

現代のSolanaアプリケーションでは、次のようなインフラが必要になります。

ウォレット残高とポートフォリオ追跡
取引履歴とインデックス作成
トークン価格と流動性データ
スワップルーティングとDeFiインタラクション
リアルタイムのブロックチェーンイベント
AIが扱いやすい構造化データ

ここでSolana APIが重要になります。

ただし、「Solana API」は単一のカテゴリではありません。プロバイダーごとに、生のRPCインフラ、DeFiルーティング、ウォレットインテリジェンス、市場データなど、解決するレイヤーが異なります。

この記事では、2026年時点で開発者、ウォレットアプリ、AIエージェントが検討すべきSolana APIを、実装観点で整理します。

CoinStats Solana API
Chainstack
Jupiter
Shyft
Birdeye
Solscan

単純な人気順ではなく、「何を解決するAPIなのか」「どのアーキテクチャに組み込むべきか」を中心に見ていきます。

優れたSolana APIとは？

APIを選ぶ前に、まずSolanaアプリケーションが必要とするデータレイヤーを分解して考える必要があります。

1. ウォレットとアカウントデータ

多くのSolanaアプリは、ウォレットの可視化から始まります。

一般的に必要になるデータは次の通りです。

トークン残高
NFT保有状況
アカウント状態
ステーキングポジション

ウォレットアプリ、資産管理ダッシュボード、AIポートフォリオツールを作る場合、このレイヤーは必須です。

実装時は、次のような情報を取得できるか確認します。

wallet_address -> token_balances
wallet_address -> transaction_history
wallet_address -> portfolio_summary
wallet_address -> staking_positions

2. 取引履歴とインデックス作成

Solanaの生データをそのまま扱うのは簡単ではありません。

実用的なAPIには、次の機能が求められます。

構造化された取引履歴
解析済み命令
イベントレベルのインデックス
フィルタリング可能なクエリ

特に分析ツールやAIエージェントでは、「取引があった」だけでなく、「何が起きたのか」を解釈できるデータが必要です。

例として、AIエージェントに渡すなら次のような構造が扱いやすくなります。

{
  "wallet": "SOLANA_WALLET_ADDRESS",
  "event": "token_swap",
  "input_token": "SOL",
  "output_token": "USDC",
  "timestamp": "2026-06-01T00:00:00Z"
}

3. DeFiとスワップインフラ

SolanaのDeFiエコシステムでは、価格、流動性、ルーティングが非常に重要です。

アプリケーションでは、次のような機能が必要になります。

スワップルーティング
流動性データ
DEX集約
プール横断の価格取得

DeFiアプリやトレーディングボットを作る場合は、RPCだけでは不十分です。スワップ実行やルート最適化に特化したAPIを組み合わせる必要があります。

4. リアルタイムパフォーマンス

Solanaアプリはレイテンシーの影響を受けやすいです。

API選定では、次を確認します。

RPC応答速度
WebSocketストリーム対応
低レイテンシーのインデックス作成
本番環境での安定性

ウォレット表示だけなら多少の遅延は許容できますが、トレーディングボットや自動実行システムではRPCの品質が直接成果に影響します。

5. AIと自動化への対応

AIワークフローでは、APIレスポンスの扱いやすさが重要です。

確認すべきポイントは次の通りです。

構造化された出力
エージェントが扱いやすいエンドポイント
文脈を含むレスポンス
ウォレットや取引の意味を解釈しやすいデータ形式

AIエージェントに生のトランザクションログを渡すより、ポートフォリオ構成、損益、資産配分、取引イベントとして整理されたデータを渡す方が実装しやすくなります。

1. CoinStats Solana API

CoinStats Solana APIは、ウォレットインテリジェンス、ポートフォリオ追跡、マルチチェーン暗号資産データを、1つの構造化されたシステムとして扱うAPIです。

残高、取引履歴、ポートフォリオ分析を別々のAPIで組み合わせる代わりに、CoinStatsはウォレットとユーザーアクティビティを中心にデータを整理します。

主に次のようなアプリケーションで使われます。

トークン全体のウォレット残高取得
アカウント横断の取引履歴取得
ポートフォリオパフォーマンス追跡
DeFiエクスポージャーと資産配分の可視化
マルチチェーンポートフォリオ集約

特に、AI駆動型アプリケーションでは「生データ」より「文脈を持ったデータ」が重要です。

例えば、単にトークン残高を返すのではなく、次のような情報を扱えると実装が簡単になります。

ポートフォリオ構成
実現損益と未実現損益
クロスチェーン資産配分
過去のウォレット挙動

実装イメージは次のようになります。

ユーザーのウォレットアドレス
        ↓
CoinStats Solana API
        ↓
残高 / 取引履歴 / ポートフォリオ分析
        ↓
ウォレットUI / AIエージェント / ダッシュボード

CoinStats APIは、次の用途に向いています。

市場データ
AIポートフォリオアシスタント
ウォレット追跡アプリケーション
自動化された暗号資産ダッシュボード
マルチチェーン分析ツール

CoinStats Solana APIは、低レベルのブロックチェーンアクセスというより、生のオンチェーンデータを金融コンテキストに変換するレイヤーです。エンドポイントの内訳とユースケースは、こちらのSolana APIガイドでも詳しく説明されています。

強み

ウォレット、ポートフォリオ、市場データを1つのAPIに統合
Solanaを含む120以上のチェーンをカバー
ポートフォリオ分析レイヤーが強い
AIエージェントに適している
複数データプロバイダーを組み合わせる必要を減らせる

最適用途

市場データフィード、ウォレットアプリ、ポートフォリオ分析、AIポートフォリオシステム、AIトレーディングボット、マルチチェーン分析プラットフォーム。

2. Chainstack

Chainstackは、Solanaアプリケーション向けにマネージドブロックチェーンノードとRPCサービスを提供します。

このリストの中では、より低レイヤーのインフラに位置します。DeFi分析やポートフォリオデータではなく、Solanaネットワークへの接続性と信頼性を提供するサービスです。

開発者は、独自にノードを運用せずにSolanaと直接やり取りするためにChainstackを使います。

一般的な用途は次の通りです。

トランザクションの送信
オンチェーン状態のクエリ
スマートコントラクトとのインタラクション
トランザクションストリームとブロックアクティビティの監視
バックエンドブロックチェーンサービスの基盤

RPCを使うアプリケーションでは、次のような流れになります。

Backend Service
      ↓
Solana RPC Endpoint
      ↓
Solana Network

JavaScriptでRPCに接続する場合の基本形は次のようになります。

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("YOUR_SOLANA_RPC_ENDPOINT");

const wallet = new PublicKey("YOUR_WALLET_ADDRESS");
const balance = await connection.getBalance(wallet);

console.log(balance);

高性能アプリケーションでは、RPCの安定性が非常に重要です。ノード応答が遅い、または不安定な場合、その上に構築されたウォレット、取引システム、AIエージェントすべてに影響します。

Chainstackは分析プラットフォームではなく、Solanaアプリケーションの基盤となるインフラプロバイダーです。

強み

Solana以外の70以上のチェーンをサポート
専用ノードとYellowstone gRPCストリーミングに対応
インフラ運用なしでスケールしやすい
AIエージェントおよびLLM向けのMCPサーバー
本番環境向けの稼働時間とパフォーマンス

最適用途

バックエンドインフラ、RPCアクセス、高性能Solanaアプリケーション。DeFiアプリ、オンチェーンボット、信頼性の高いRPCが必要なAIエージェントに適しています。

3. Jupiter

Jupiterは、Solanaエコシステムで重要な流動性アグリゲーションプロトコルの1つです。

一般的なデータAPIというより、分散型取引所間のスワップルーティングに特化しています。

ユーザーがトークンスワップを実行する際、Jupiterは利用可能な流動性ソースから効率的なルートを探します。

開発者は主に次のようなシステムでJupiterを使います。

スワップインターフェース
トレーディングボット
DeFiアプリケーション
自動ポートフォリオリバランサー

Jupiterの価値は、Solana DEX間に分散した流動性を扱いやすくすることです。

各DEXを個別に統合する代わりに、Jupiterを統合ルーティングレイヤーとして使えます。

実装イメージは次の通りです。

ユーザーがスワップを要求
        ↓
Jupiterでルート取得
        ↓
スワップトランザクション生成
        ↓
ウォレット署名
        ↓
Solanaへ送信

AIエージェントにとっても、Jupiterは次の用途で有用です。

自動取引実行
最適化されたスワップ判断
クロスDEX流動性アクセス

Jupiterは単なるデータ取得よりも、実行インテリジェンスに重点を置いたレイヤーです。

強み

スワップルーティングに強い
Solanaの流動性を集約
DeFi統合を簡素化
自動化システムと相性が良い

最適用途

DeFiアプリ、トレーディングボット、自動実行システム。

4. Shyft

Shyftは、Solanaアプリケーション向けに、アイデンティティ、コンプライアンス、構造化ブロックチェーンデータサービスを提供します。

生のブロックチェーンデータを、より読みやすく、企業向けに扱いやすい形式へ変換することに焦点を当てています。

生のトランザクションログの代わりに、Shyftでは次のようなデータを扱えます。

解析済みトランザクションデータ
IDにリンクされたウォレット情報
構造化されたイベント追跡
コンプライアンス指向のブロックチェーンインサイト

生データを直接扱う場合、アプリ側で解析処理を実装する必要があります。

Raw Transaction
      ↓
Parser
      ↓
Application Event
      ↓
Dashboard / AI / Compliance Tool

Shyftは、この解析部分を簡略化するために使われます。

一般的な用途は次の通りです。

フィンテックアプリケーション
コンプライアンスダッシュボード
分析プラットフォーム
企業向けブロックチェーンツール

AIシステムにとって、構造化データは曖昧さを減らし、推論の品質を上げるために重要です。

Shyftは、生のブロックチェーンデータとアプリケーションレベルのインテリジェンスの間をつなぐAPIとして使えます。

強み

構造化され解析済みのブロックチェーンデータ
IDおよびコンプライアンス機能
企業向けアプリに有用
AIフレンドリーなデータフォーマット

最適用途

コンプライアンスツール、構造化分析、エンタープライズSolanaアプリケーション。

5. Birdeye

Birdeyeは、Solanaに特化した市場データおよび分析プラットフォームです。

Solanaエコシステム全体のトークンパフォーマンス、流動性、取引活動に関するデータを提供します。

開発者はBirdeyeを次の用途で使います。

トークン価格追跡
流動性分析
DEX取引データ
リアルタイム市場フィード

特に、Solana固有の市場データを高速に扱いたいダッシュボードや取引ツールで使いやすいAPIです。

一般的な暗号資産APIとは異なり、BirdeyeはSolanaネイティブの市場行動に特化しています。

実装上は、次のような構成で使われます。

Birdeye Market Data
        ↓
価格 / 流動性 / DEX取引データ
        ↓
チャート / アラート / トレーディングシグナル

AIシステムでは、Birdeyeのデータを次の用途に使えます。

シグナル生成
取引戦略分析
市場監視

強み

Solana市場データに強い
リアルタイムDEXデータ
トークンレベルの分析
トレーディングダッシュボードに適している

最適用途

市場ダッシュボード、取引分析、Solanaトークントラッキング。

6. Solscan

Solscanは、広く使われているSolanaブロックチェーンエクスプローラーおよびデータAPIの1つです。

次のような情報にアクセスできます。

取引履歴
ウォレットアクティビティ
トークンメタデータ
ブロックレベルの情報

Solscanは、視覚的なエクスプローラーとしても、開発者向けAPIとしても使われます。

開発者は次のような場面でSolscanを使います。

生のブロックチェーン透明性が必要な場合
ウォレットレベルの検査をしたい場合
取引検証を行いたい場合
デバッグや分析ツールを作る場合

高レベルのポートフォリオAPIとは異なり、Solscanは生のチェーンデータに近い情報を扱うため、調査や検証に向いています。

用途としては次のようなものがあります。

フォレンジックブロックチェーン分析
デバッグツール
エクスプローラーベースのアプリケーション

強み

透明性の高いブロックチェーンデータアクセス
強力なエクスプローラーインフラ
デバッグと分析に有用
広く採用されている

最適用途

ブロックチェーンエクスプローラー、デバッグツール、生のSolanaデータアクセス。

比較表

API	主な役割	向いている用途	レイヤー
CoinStats Solana API	ウォレット、ポートフォリオ、市場データ	ウォレットアプリ、AIポートフォリオ、マルチチェーン分析	アプリケーションデータ
Chainstack	Solana RPC、ノードインフラ	バックエンド、DeFiアプリ、オンチェーンボット	インフラ
Jupiter	スワップルーティング、流動性集約	DeFi、トレーディングボット、自動実行	DeFi実行
Shyft	構造化データ、ID、コンプライアンス	企業向けアプリ、分析、コンプライアンス	データ解析
Birdeye	市場データ、DEXデータ	価格追跡、取引分析、ダッシュボード	市場データ
Solscan	エクスプローラー、取引検証	デバッグ、調査、チェーン分析	ブロックチェーンデータ

どのSolana APIを選ぶべきか？

用途別に選ぶと、判断しやすくなります。

ウォレットアプリ、ポートフォリオダッシュボード、AIポートフォリオシステムを構築していて、構造化された金融コンテキストが必要な場合は、CoinStats APIを選択します。

信頼性の高いSolana RPCインフラが必要な場合は、Chainstackを選択します。

アプリケーションがスワップやDeFi実行に依存している場合は、Jupiterを選択します。

構造化データやコンプライアンス向けのブロックチェーンデータが必要な場合は、Shyftを選択します。

Solanaネイティブの市場分析が必要な場合は、Birdeyeを選択します。

生のブロックチェーン透明性、取引検証、デバッグ用途が中心なら、Solscanを選択します。

実際のプロダクトでは、1つのAPIだけで完結しないこともあります。

例えば、次のような構成が考えられます。

Chainstack -> RPC基盤
Jupiter    -> スワップ実行
Birdeye    -> 市場データ
CoinStats  -> ウォレットとポートフォリオ分析
Solscan    -> デバッグと検証

重要なのは、APIを「Solanaデータ取得ツール」として一括りにせず、必要なレイヤーごとに選ぶことです。

最後に

Solanaエコシステムは拡大を続けており、現代の暗号資産アプリケーションに求められる要件も増えています。

多くのプロジェクトでは、単純なブロックチェーンアクセスだけでは不十分です。ウォレットインテリジェンス、取引監視、ポートフォリオ分析、市場データ、DeFiの可視性を、1つのプロダクト体験として連携させる必要があります。

Chainstack、Jupiter、Shyft、Birdeye、Solscanは、それぞれSolanaインフラスタックの重要な部分を解決します。

一方で、CoinStats APIは、ウォレット追跡、ポートフォリオ分析、市場インテリジェンス、マルチチェーン可視性を1つのプラットフォームに統合するアプローチを取っています。

開発者にとっては、統合するAPIの数を減らし、バックエンドの複雑さを抑え、プロトタイプから本番化までの実装スピードを上げられる可能性があります。

最終的に最適なSolana APIは、あなたのアプリケーションが次のどれを中心にしているかで決まります。

インフラ
取引実行
市場分析
ウォレットインテリジェンス
AI駆動の暗号資産体験

まずは必要なデータレイヤーを分解し、その上でAPIを組み合わせるのが、Solanaアプリケーション開発の実践的な進め方です。

ロールベースアクセス制御（RBAC）でAPI連携のセキュリティを確保する方法

Akira — Fri, 05 Jun 2026 10:40:03 +0000

要点: ロールベースのアクセスコントロール (RBAC) は、個々のユーザーではなく「ロール」に権限を割り当てるアクセス制御モデルです。APIチームでは、APIコラボレーションを安全にスケールさせるために、組織 → チーム → プロジェクトの3階層で権限を設計することが重要です。Apidogは、3つのレベルにわたる12の組み込みロールと、Enterprise向けのカスタムプロジェクトロールを提供し、APIアセットの表示、編集、テスト、管理を細かく制御できます。

今すぐApidogを試す

APIチームでRBACが必要になる理由

API開発には、開発者、QA、プロダクトマネージャー、テクニカルライター、セキュリティ担当者など複数のロールが関わります。全員に同じ権限を付与すると、次のような問題が起きやすくなります。

ジュニア開発者が本番API仕様を誤って変更する
請負業者が機密性の高い決済APIにアクセスする
退職者のアカウントが長期間有効なまま残る
誰がどのAPIを変更したか追跡できない

RBACでは、ユーザー単位ではなくロール単位で権限を管理します。

実装上のメリットは次のとおりです。

権限変更が簡単

ユーザーのロールを変更するだけで、アクセス範囲をまとめて更新できます。
最小特権を適用しやすい

各ロールに必要最低限の操作だけを許可できます。
監査しやすい

アクションをロールとユーザーにひも付けて確認できます。
チーム拡大に対応しやすい

新しいメンバーを追加するときも、個別権限ではなくロールを割り当てるだけで済みます。

Apidogは、API開発ワークフロー向けに設計された3層権限モデルを提供しています。

3段階の権限階層

ApidogのRBACは、次の3階層で構成されます。

レベル	範囲	制御するもの
組織	会社全体	請求、SSO、メンバー管理、カスタムロール定義
チーム	部門 / 事業単位	チームメンバー、プロジェクト作成、チームリソース
プロジェクト	個々のAPI	エンドポイント、テスト、ドキュメント、環境、ブランチ

たとえば、決済、ID、分析の3チームを持つ企業では、決済チームの開発者は決済APIにアクセスできるべきですが、IDや分析APIにはアクセスできない場合があります。一方、組織管理者はSSOやメンバー管理を担当しますが、すべてのAPIエンドポイントを編集する必要はありません。

3階層で分けることで、次の失敗を避けられます。

過剰な権限付与: 全員に管理者権限を与えてしまう
権限のギャップ: チーム単位では制御できるが、プロジェクト単位では制御できない

組織レベルのロールと権限

組織のロールは、会社全体の設定を管理します。請求、SSO、メンバー、チーム、組織リソースなどに影響します。

組み込みの組織ロール

ロール	説明	主な機能
組織オーナー	組織の作成者、最高権限者	組織名の変更、移管、解散、完全な管理者権限
組織管理者	組織の管理者	メンバー、チーム、SSO、カスタムロール、組織リソースの管理
組織メンバー	基本的な参加者	チームやプロジェクトへの参加
請求管理者	請求管理専用	サブスクリプションと請求の管理

組織設定の権限

機能	組織オーナー	組織管理者	組織メンバー	請求管理者
組織設定へのアクセス	✅	✅	❌	❌
組織名の変更	✅	✅	❌	❌
組織の所有権の移管	✅	❌	❌	❌
組織の解散	✅	❌	❌	❌

チーム管理の権限

機能	組織オーナー	組織管理者	組織メンバー	請求管理者
新しいチームの作成	✅	✅	❌	❌
チームを組織に移管	✅	✅	❌	❌
チームを組織外に移管	✅	✅	❌	❌

メンバー管理の権限

機能	組織オーナー	組織管理者	組織メンバー	請求管理者
メンバーの招待	✅	✅	❌	❌
メンバーの組織ロールの変更	✅	✅	❌	❌
メンバーの削除	✅	✅	❌	❌

組織メンバーは、組織設定を管理できない制限付きロールです。チームやプロジェクトの権限に基づいて作業できますが、組織全体に影響する操作はできません。

請求管理者は独立したロールです。ユーザーは組織メンバーかつ請求管理者になることができますが、請求管理者だけではSSOやメンバー管理にはアクセスできません。

チームレベルのロールと権限

チームロールは、部門やプロダクトチーム単位の操作を管理します。チームは、モバイル、バックエンド、QA、決済などの単位で設計できます。

組み込みのチームロール

ロール	説明	主な機能
チームオーナー	チーム作成者	チームの移管、解散、すべてのチーム設定
チーム管理者	チーム管理者	メンバー招待、ロール割り当て、プロジェクト作成 / 削除
チームメンバー	チーム参加者	メンバー詳細の表示、プロジェクト参加
ゲスト	外部コラボレーター	チーム管理なし、プロジェクトアクセスのみ

チーム管理の権限

権限	チームオーナー	チーム管理者	チームメンバー	ゲスト
チームメンバー詳細の表示	✅	✅	✅	❌
チームメンバーの招待	✅	✅	❌	❌
チームメンバーロールの割り当て / 削除	✅	✅	❌	❌
プロジェクトロールの表示	✅	✅	❌	❌
プロジェクトロールの追加 / 編集 / 削除	✅	✅	❌	❌

チーム設定の権限

権限	チームオーナー	チーム管理者	チームメンバー	ゲスト
チーム名の編集	✅	✅	❌	❌
チームの移管	✅	❌	❌	❌
チームの解散	✅	❌	❌	❌

プロジェクト操作の権限

権限	チームオーナー	チーム管理者	チームメンバー	ゲスト
新しいプロジェクトの作成	✅	✅	❌	❌
プロジェクトのクローン	✅	✅	❌	❌
プロジェクトの削除 / 移管	✅	✅	❌	❌
プロジェクト名の編集	✅	✅	❌	❌

ゲストロールは、請負業者やコンサルタントなどの外部協力者に向いています。チーム管理機能や他のプロジェクトにはアクセスさせず、必要なプロジェクトだけを共有できます。

プロジェクトレベルのロールと権限

プロジェクトロールは、API単位の操作を制御します。エンドポイント編集、テスト実行、環境管理、ドキュメント公開など、日常的なAPI作業はこのレベルで管理します。

組み込みのプロジェクトロール

ロール	説明	ユースケース
管理者	プロジェクトの完全な制御	プロジェクトリード、APIオーナー
編集者	コンテンツの変更	開発者、QAエンジニア
閲覧者	表示と実行のみ	PM、レビュー担当者、ステークホルダー
禁止	アクセスなし	機密プロジェクト、制限対象ユーザー

プロジェクト権限のカテゴリ

プロジェクト権限は、主に次のカテゴリで管理します。

ブランチ管理

スプリントブランチ、マージリクエスト、保護されたブランチ、APIバージョン
エンドポイント管理

エンドポイント、ケース、スキーマ、コンポーネント、リクエスト、ゴミ箱操作
自動テスト

テストシナリオ、パフォーマンステスト、スケジュールタスク、テストレポート
環境管理

グローバル変数、パラメータ、環境、Vaultシークレット
ドキュメント共有

クイック共有、ドキュメントサイト公開
プロジェクト設定

基本設定、メンバー管理、機能設定、通知
リクエスト履歴

ローカルおよび共有リクエスト履歴
インポート / エクスポート

データインポート、スケジュールインポート、エクスポート操作

主要な権限

権限	管理者	編集者	閲覧者	禁止
エンドポイントの表示、実行	✅	✅	✅	❌
エンドポイントの追加、削除、変更	✅	✅	❌	❌
機能テストの実行	✅	✅	✅	❌
テストシナリオの追加、削除、変更	✅	✅	❌	❌
環境変数の表示、編集	✅	✅	✅	❌
環境の追加、削除、変更	✅	✅	❌	❌
Vaultシークレットへのアクセス	✅	✅	❌	❌
ドキュメントサイト公開設定	✅	❌	❌	❌
プロジェクトのクローン	✅	❌	❌	❌
プロジェクトメンバーの管理	✅	❌	❌	❌

禁止ロールは、特定プロジェクトへのアクセスを明示的に拒否するために使います。ユーザーをチームから削除せずに、機密APIだけを見せない構成にできます。

カスタムロールで権限を細かく制御する

組み込みロールで足りない場合は、きめ細かな権限を持つカスタムプロジェクトロールを設計します。ApidogのEnterpriseプランでは、カスタムプロジェクトロールを利用できます。

カスタムロールの例

ロール例	許可する操作	制限する操作
QAエンジニア	テスト実行、テストシナリオ編集	API仕様の編集
テクニカルライター	ドキュメント編集	エンドポイント、環境の変更
セキュリティ監査人	閲覧、Vaultシークレット確認	変更操作
インターン	エンドポイント表示、リクエスト実行	削除操作

カスタムプロジェクトロールの作成手順

チーム → メンバー → ロールと権限に移動します。

または、組織単位で管理する場合は組織 → メンバー → ロールと権限に移動します。
+ 追加をクリックします。
既存ロールをコピーするか、新しいロールを作成します。
必要な権限カテゴリを選択します。

設定できる主なカテゴリは次のとおりです。

カテゴリ	きめ細かな制御
ブランチ管理	ブランチの表示、マージ、マージリクエスト送信、保護されたブランチの変更
エンドポイント管理	表示 / 実行、追加 / 変更 / 削除、コード生成、ケース / スキーマ / コンポーネント / リクエスト管理
自動テスト	機能テスト、パフォーマンステスト、シナリオ変更、スケジュールタスク、レポート削除
環境管理	現在値の表示 / 編集、環境の追加 / 変更 / 削除、Vaultシークレット管理
ドキュメント	クイック共有、ドキュメントサイトのプレビュー、公開設定
プロジェクト設定	設定表示、設定変更、メンバー管理、通知、インポート / エクスポート
リクエスト履歴	ローカル履歴、履歴共有、共有履歴表示、共有履歴削除

カスタムロール設計のベストプラクティス

既存ロールをコピーして始める

編集者や閲覧者をベースに調整すると、設定漏れを減らせます。
「すべての権限」チェックボックスを慎重に使う

モジュールに将来追加される権限も自動付与されます。
本番適用前にテストする

テストプロジェクトで実際の操作可否を確認します。
ロール定義を文書化する

ロール名、目的、許可される操作、付与対象を明記します。
四半期ごとに棚卸しする

権限の肥大化や不要なカスタムロールを確認します。

エンタープライズセキュリティ機能

RBACだけではなく、ID管理やシークレット管理も合わせて設計すると、APIコラボレーションのセキュリティを強化できます。

SSO

SAML 2.0によるSSOにより、次のようなIDプロバイダーを使って認証を一元化できます。

Microsoft Entra ID (Azure Active Directory)
Okta
Google Workspace
OneLogin
カスタムSAML 2.0プロバイダー

SSOを使う理由は次のとおりです。

ローカルパスワード管理のリスクを減らす
ID管理をIdPに集約する
IdP側のMFAをApidogアクセスにも適用する
新入社員のオンボーディングを簡素化する

SCIMプロビジョニング

SCIM (System for Cross-domain Identity Management)は、ユーザーの作成や削除を自動化します。

機能	実行内容
ユーザーの追加	IdPでユーザーが作成されると、Apidog組織にも追加される
ユーザーの削除	IdPでユーザーが削除されると、Apidogからも削除される
アカウントのリンク	SSO IDが既存のApidogアカウントにリンクされる

SCIMを有効にすると、退職者のアクセスを手動で削除する必要が減り、不要なアカウントが残るリスクを抑えられます。

チームへのグループマッピング

ApidogはSAMLグループマッピングをサポートしています。IdPグループをApidogチームにマッピングすることで、チーム割り当てを自動化できます。

手順は次のとおりです。

IdPでグループクレームを設定します。
各IdPグループをApidogチームにマッピングします。
各グループにチームロールを設定します。
パイロットユーザーでログインをテストします。

例:

Azure ADグループ「API開発者」→ Apidogの「バックエンドチーム」→ チームメンバー
Azure ADグループ「API管理者」→ Apidogの「プラットフォームチーム」→ チーム管理者

ユーザーがSSOでサインインすると、グループに基づいて適切なチームとロールが割り当てられます。

Vaultシークレット

Vaultシークレットは、APIキー、パスワード、トークンなどの認証情報を集中管理する機能です。

機能	セキュリティ上の利点
暗号化されたストレージ	APIキーやトークンを暗号化して保存
参照ベースのアクセス	ユーザーは名前で参照し、実際の値を直接見ない
ロールベースの可視性	管理者や編集者など、許可されたロールだけが操作可能
監査証跡	シークレットアクセスをログとして確認可能

ローカル環境ファイルと比較すると、Vaultシークレットは集中管理、暗号化、ロール制御、監査に対応できる点が重要です。

アプローチ	セキュリティリスク
ローカル環境ファイル	プロジェクト参加者にシークレットが見える可能性があり、Git経由で漏洩するリスクがある
Vaultシークレット	集中管理され、暗号化され、ロールで制御され、監査可能

ApidogでRBACを設定する手順

ここでは、一般的なAPI組織を例にRBACを設計します。

ステップ1: チーム構造を定義する

まず、組織、チーム、プロジェクトの構造を書き出します。

組織: あなたの会社
├── チーム: 決済
│   ├── プロジェクト: 決済ゲートウェイAPI
│   ├── プロジェクト: 不正検出API
│   └── プロジェクト: 請求サービスAPI
├── チーム: ID
│   ├── プロジェクト: 認証サービスAPI
│   └── プロジェクト: ユーザー管理API
└── チーム: 分析
    ├── プロジェクト: メトリクスAPI
    └── プロジェクト: レポートAPI

ステップ2: 組織ロールを設定する

最初は、組織全体の管理者を少人数に絞ります。

組織オーナー: 1名

例: CTO、プラットフォームリード
組織管理者: 2〜3名

例: エンジニアリングマネージャー、セキュリティリード
組織メンバー: その他全員

例: 開発者、QA、PM、ライター

ステップ3: チームロールを設定する

各チームに、オーナー、管理者、メンバーを割り当てます。

チーム	チームオーナー	チーム管理者	チームメンバー
決済	決済リード	決済マネージャー	開発者5名、QA2名
ID	IDリード	IDマネージャー	開発者3名、QA1名
分析	分析リード	分析マネージャー	開発者2名

ステップ4: プロジェクトロールを設定する

各プロジェクトでは、責任に応じて管理者、編集者、閲覧者、禁止を割り当てます。

人物	決済ゲートウェイAPI	不正検出API	認証サービスAPI
シニア開発者A	管理者	編集者	禁止
シニア開発者B	編集者	管理者	禁止
ジュニア開発者C	編集者	閲覧者	禁止
QAエンジニア	編集者	編集者	禁止
プロダクトマネージャー	閲覧者	閲覧者	禁止
請負業者	編集者	禁止	禁止

ステップ5: ロール付きでメンバーを招待する

招待時に、チームロールとプロジェクトロールを同時に設定します。

チーム招待

チームロールとデフォルトのプロジェクトロールを指定します。
プロジェクト招待

特定プロジェクトのロールを指定し、自動的にチームへ追加します。

外部協力者には、プロジェクト単位の招待を使い、他のプロジェクトは禁止に設定すると安全です。

ステップ6: SSOとSCIMを設定する

Enterprise環境では、次の順序で設定します。

組織設定でSAML SSOをセットアップする
IdP側でSCIMトークンを設定する
IdPグループをApidogチームにマッピングする
パイロットグループでサインインとロール割り当てを検証する
全社展開する

APIコラボレーションセキュリティのベストプラクティス

1. 最小特権から始める

最初から広い権限を与えず、必要に応じて追加します。

新しいチームメンバー: 閲覧者から開始
請負業者: 割り当てプロジェクトのみ編集者、その他は禁止
QAエンジニア: テストは編集者、仕様は閲覧者

2. 開発、ステージング、本番のアクセスを分離する

環境ごとにプロジェクトまたはブランチを分け、操作可能なロールを変えます。

環境	開発者アクセス	QAアクセス	管理者アクセス
開発	編集者	編集者	管理者
ステージング	閲覧者	編集者	管理者
本番	禁止	閲覧者	管理者

3. 特殊な業務にはカスタムロールを使う

汎用ロールで無理に対応せず、必要な権限だけを持つロールを作成します。

セキュリティチーム: 閲覧者 + Vaultシークレットアクセス
テクニカルライター: ドキュメント編集、エンドポイント閲覧
パフォーマンスエンジニア: テスト編集、仕様閲覧

4. 四半期ごとに権限を見直す

RBACは一度設定して終わりではありません。定期的に棚卸しします。

確認項目:

退職者や異動者のアクセスが残っていないか
請負業者のアクセス範囲が広すぎないか
カスタムロールが現在の業務に合っているか
管理者権限を持つユーザーが多すぎないか

5. ロール定義を文書化する

チーム内で、次の内容を明確にします。

各ロールでできること / できないこと
誰にどのロールを付与するか
ロール変更の申請方法
アクセス権限に関するエスカレーション先

6. 監査ログを活用する

Enterpriseプランでは、監査ログによって次の情報を確認できます。

誰がアクセスしたか
いつアクセスしたか
どの操作を実行したか
ロールがいつ変更されたか

監査ログは、コンプライアンス報告、セキュリティインシデント調査、権限最適化に役立ちます。

RBACの比較: Apidogとその他のツール

機能	Apidog	Postman	SwaggerHub	Bruno
権限レベル	3 (組織 / チーム / プロジェクト)	2 (組織 / チーム)	2 (組織 / ワークスペース)	1 (Gitベース)
組み込みロール	12ロール	5ロール	4ロール	なし (Git権限)
カスタムロール	✅ (エンタープライズ)	✅ (エンタープライズ)	✅ (エンタープライズ)	❌
SSO / SAML	✅	✅	✅	❌
SCIMプロビジョニング	✅	✅	❌	❌
グループマッピング	✅	✅	✅	❌
Vaultシークレット	✅	✅ (エンタープライズ)	❌	❌
プロジェクト分離	✅ (禁止ロール)	限定的	限定的	Gitベース
外部協力者制御	✅ (ゲスト + 禁止)	限定的	限定的	Gitアクセス制御

ApidogのRBACは、次のようなチームに向いています。

複数のAPIチームを持つ組織
SSO、SCIM、監査ログが必要なエンタープライズ環境
開発者、QA、PM、セキュリティ、ライターが共同作業するチーム
外部協力者に限定的なアクセスを付与したいチーム
決済APIや認証APIなど、機密性の高いAPIを扱うチーム

結論

RBACは、APIコラボレーションを安全にスケールさせるための基本設計です。ユーザーごとに権限を直接管理するのではなく、組織、チーム、プロジェクトの3階層でロールを設計することで、最小特権、監査性、運用効率を両立できます。

重要なポイントは次のとおりです。

3段階の階層（組織 → チーム → プロジェクト）は、実際のチーム構造に合う
12の組み込みロールで標準的なシナリオをカバーできる
カスタムプロジェクトロールで特殊な業務に対応できる
SSOとSCIMでID管理を自動化できる
Vaultシークレットで認証情報を集中管理できる
禁止ロールで機密プロジェクトへのアクセスを明示的に拒否できる
グループマッピングでIdPグループからチーム割り当てを自動化できる

ApidogのRBACシステムは、小規模チームからエンタープライズ組織まで、APIコラボレーションのアクセス制御を実装するための基盤になります。

よくある質問: APIチームのためのRBAC

API開発におけるRBACとは何ですか？

API開発におけるRBACは、個々のユーザーではなくロールに権限を割り当てるモデルです。ユーザーは管理者、編集者、閲覧者などのロールを受け取り、そのロールによってAPIリソースの表示、変更、テスト、管理の可否が決まります。

APIコラボレーションにはなぜ3段階の権限が必要ですか？

APIチームでは、組織全体の管理、チーム単位の管理、プロジェクト単位のAPI操作が分かれています。3段階のRBACにより、SSOや請求などの組織管理、プロジェクト作成などのチーム管理、エンドポイント編集などのプロジェクト操作を分離できます。

組織管理者とチーム管理者の違いは何ですか？

組織管理者は、メンバー招待、チーム作成、SSO設定、カスタムロール定義など会社全体の設定を管理します。チーム管理者は、チームメンバーの招待、チーム内プロジェクトの作成、チームリソースの設定など、特定チーム内の操作を管理します。

「禁止」プロジェクトロールはどのように機能しますか？

「禁止」ロールは、特定プロジェクトへのアクセスを明示的に拒否します。ユーザーはチームメンバーのままでいられますが、そのプロジェクトの内容は表示できません。決済APIやセキュリティ関連APIなど、機密性の高いプロジェクトに有効です。

「ゲスト」チームロールは何のためにありますか？

ゲストロールは、請負業者、コンサルタント、外部協力者向けです。ゲストはチーム管理機能にアクセスできず、プロジェクトレベルで許可された範囲だけ作業できます。

特定の権限を持つカスタムロールを作成できますか？

はい。Apidog Enterpriseプランでは、ブランチ管理、エンドポイント管理、自動テスト、環境管理、ドキュメント共有、プロジェクト設定、リクエスト履歴、インポート / エクスポートなどのカテゴリに対して、きめ細かな権限を持つカスタムプロジェクトロールを作成できます。

SSO統合はRBACとどのように連携しますか？

SSOは、OktaやMicrosoft Entra IDなどのIdPを通じて認証を一元化します。さらに、IdPグループをApidogチームやロールにマッピングすることで、グループメンバーシップに基づいて適切な権限を自動的に割り当てられます。

SCIMプロビジョニングとは何ですか？

SCIMは、ユーザーライフサイクル管理を自動化する仕組みです。入社時にはアカウントを自動作成し、退職時にはアクセスを削除できます。手動の招待や削除を減らし、不要なアカウントが残るリスクを抑えます。

VaultシークレットはRBACとどのように連携しますか？

Vaultシークレットは、APIキー、パスワード、トークンなどを暗号化して集中管理します。RBACにより、誰がシークレットを追加、変更、参照できるかを制御できます。これにより、環境ファイルやGitリポジトリ経由の認証情報漏洩を防ぎやすくなります。

請負業者にはどのロールを付与すべきですか？

通常は、チームレベルではゲスト、プロジェクトレベルでは必要に応じて編集者または閲覧者を付与します。関係のないプロジェクトには「禁止」を設定し、割り当てられたプロジェクトだけにアクセスを限定するのが安全です。

Stoplight + Postman vs Apidog: API設計、ドキュメント、テストの統合プラットフォーム

Akira — Fri, 05 Jun 2026 08:42:27 +0000

OpenAPIの設計・ドキュメントにStoplight、コレクション・テストにPostmanを使っている場合、よく起きる問題は「仕様」と「テスト」が別々に管理されることです。APIコントラクトは1つなのに、Stoplight側のOpenAPI仕様とPostman側のコレクションを個別に更新する必要があります。Apidogは、OpenAPI仕様を設計、ドキュメント、モック、自動テストの単一の信頼できる情報源として扱い、Gitに接続されたワークスペースからAPIライフサイクルをまとめて管理できます。

今すぐApidogを試す

この記事では、StoplightとPostmanを併用する場合の実装上の課題、Apidogに集約する判断ポイント、移行前に検証すべき項目を整理します。仕様ファーストの考え方を確認したい場合は、スペックファーストAPI開発とは？も参考にしてください。

2つのツールを使うと起きる問題

StoplightとPostmanは、それぞれAPIライフサイクルの別領域に強みがあります。

Stoplight: 視覚的なOpenAPIエディタ、Gitベースの仕様管理、自動生成ドキュメント
Postman: コレクション、環境変数、事前リクエストスクリプト、テスト実行、CI実行

組み合わせれば設計からテストまでをカバーできますが、実装現場では次の問題が発生しやすくなります。

1. 仕様とテストが乖離する

OpenAPI仕様はStoplightが管理するGitリポジトリにあり、PostmanコレクションはPostman側にあります。

たとえば、開発者がOpenAPI仕様でリクエストボディのスキーマを変更しても、Postmanのテストは自動更新されません。その結果、QAが古いコレクションを実行し、プロダクトの不具合ではなくツール間の不整合による失敗を調査することになります。

2. 同じ情報を2か所でメンテナンスする

次のような情報は、OpenAPI仕様とPostmanコレクションの両方に現れます。

パスパラメータ
ベースURL
環境別URL
認証方式
リクエスト/レスポンススキーマ

ステージング、本番、EUリージョンなど環境が増えるたびに、StoplightとPostmanの両方を更新する必要があります。

3. 1つのAPIコントラクトに対して請求ラインが2つになる

StoplightのチームプランとPostmanのチームプランを併用すると、1つのAPI契約を管理するために2つの予算項目が発生します。

ツールの役割が明確に分かれている場合は問題ありませんが、仕様、ドキュメント、モック、テストを同じAPIコントラクトから生成したいチームでは、統合プラットフォームのほうが運用コストを下げやすくなります。

Stoplightが得意なこと

Stoplightの強みは、OpenAPI仕様を視覚的に編集できることです。

主な機能は次のとおりです。

YAML/JSONのリアルタイム検証
Spectralによるスタイルガイド適用
非エンジニアにも読みやすいフォームビュー
GitHub/GitLabとの連携
ブランチ保護ルールを使った仕様レビュー
自動生成ドキュメント

Stoplight Docsでは、カスタムドメインでの公開、toc.jsonによる目次制御、内部向けパスの制御、API Explorerの埋め込みなどもできます。

ただし、Stoplightは実行フェーズには強くありません。テストランナー、アサーションエンジン、CIテストレポートは提供されないため、テストはPostmanなど別ツールに移す必要があります。

Postmanが得意なこと

PostmanはAPIリクエストの実行とテストに強いツールです。

代表的な機能は次のとおりです。

コレクションによるリクエスト管理
環境変数
事前リクエストスクリプト
pm.test() によるJavaScriptアサーション
コレクションランナー
Newman CLIによるCI実行
モニターによる定期実行

Postmanのテストは、次のように書けます。

pm.test("Status is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has orderId", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
});

一方で、PostmanコレクションはOpenAPI仕様からインポートされた時点で分岐しやすい構造です。仕様変更を反映するには、再インポートまたは独自の同期スクリプトが必要になります。

プラットフォーム比較：Stoplight vs Postman vs Apidog

機能	Stoplight	Postman	Apidog
ビジュアルOpenAPIエディタ	ネイティブ	部分的	ネイティブ
Spectral / リントルール	ネイティブ	なし	ネイティブ
Gitリポジトリ同期（GitHub, GitLab）	ネイティブ	なし	ネイティブ（スペックファーストモード、ベータ）
ブランチベースのスペックワークフロー	ネイティブ	なし	ネイティブ
自動生成リファレンスドキュメント	ネイティブ	部分的	ネイティブ
インタラクティブドキュメント	ネイティブ	なし	ネイティブ
プライベートドキュメントアクセス制御	ネイティブ	なし	トライアルで検証の価値あり
スペックからのモックサーバー	部分的（Prism）	部分的	ネイティブ
リクエストコレクションランナー	なし	ネイティブ	ネイティブ
JavaScriptテストスクリプト	なし	ネイティブ	ネイティブ
ビジュアルアサーションエディタ	なし	なし	ネイティブ
環境変数管理	なし	ネイティブ	ネイティブ
CI/CD統合（Newman / CLI）	なし	ネイティブ	ネイティブ
スペックからのコントラクトテスト	なし	なし	ネイティブ
プロジェクト間のスキーマ再利用	部分的	なし	トライアルで検証の価値あり
SSO / SCIM	あり（エンタープライズ）	あり（エンタープライズ）	要件と照合して確認
監査ログ	あり	あり	要件と照合して確認

「トライアルで検証の価値あり」とした項目は、組織構造や運用ルールによって評価が変わります。特に、プロジェクト間のスキーマ再利用、レポート権限、監査ログは、実データを使った概念実証で確認してください。

Apidogのスペックファーストモードで変わること

Apidogのスペックファーストモードは、既存のGitHubまたはGitLabリポジトリをOpenAPI仕様の信頼できる情報源として接続します。

一度だけOpenAPIをインポートするのではなく、Git上のコミットとApidogワークスペースを同期します。

実装上のメリットは次のとおりです。

既存のOpenAPIリポジトリをそのまま使える
YAMLファイルを別形式に移行する必要がない
スペックからモックサーバーを生成できる
フロントエンドはバックエンド実装前にAPIレスポンスを使える
スペックからテストケースとアサーションを生成できる
ドキュメントが同じスペックから生成される

セットアップの詳細は、スペックファーストモードのガイドを参照してください。スペックファーストとデザインファーストの違いは、スペックファーストまたはデザインファースト：どちらのApidogモードを使用すべきか？で整理されています。

実践例：OpenAPI仕様からコントラクトテストを作る

例として、GET /orders/{orderId} エンドポイントを考えます。

Postmanでは、レスポンス検証を手動で書く必要があります。

// Postmanテストタブ：仕様とは別に管理される
pm.test("Status is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has orderId", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
  pm.expect(json.orderId).to.be.a("string");
});

このテストは有効ですが、OpenAPI仕様と別管理です。

たとえば、仕様側で status と createdAt を必須フィールドに追加しても、Postmanコレクションを更新しなければテストは古いままです。

OpenAPI仕様では、次のようにレスポンススキーマを定義できます。

# Gitリポジトリ内のOpenAPIスニペット
# 例: openapi/orders.yaml

paths:
  /orders/{orderId}:
    get:
      summary: IDで注文を取得
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 注文が見つかりました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

components:
  schemas:
    Order:
      type: object
      required:
        - orderId
        - status
        - createdAt
      properties:
        orderId:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - shipped
            - delivered
        createdAt:
          type: string
          format: date-time

Apidogのスペックファーストモードでは、このOpenAPIスキーマがテストケースのコントラクトアサーションに反映されます。

たとえば、APIレスポンスから status が欠落した場合、仕様上は必須フィールドなのでテストは失敗します。手動でPostmanテストを更新する必要はありません。

OpenAPI仕様をGitで管理する方法については、GitでOpenAPIスペックをバージョン管理する方法を参照してください。

移行前に確認すべきガバナンス項目

StoplightとPostmanからApidogへ集約する前に、次の項目は実際の試用環境で確認してください。

レポート可視性権限

CIテストレポートを特定のチーム、プロジェクト、ロールに限定できるか確認します。

確認観点:

プロジェクト単位でレポートを分離できるか
チーム外メンバーがレポートを閲覧できないか
CI実行結果へのアクセス権を制御できるか

SSOとSCIMプロビジョニング

ApidogはSSOをサポートしています。ただし、実運用前にはIDプロバイダーと接続して次を確認してください。

SSOログインの挙動
グループ同期
ユーザープロビジョニング
ユーザーの無効化・削除
権限の同期

SCIMの期待動作はSCIM RFCに定義されています。

プロジェクト間のスキーマ再利用

複数APIで共通の $ref スキーマを使っている場合、Apidogのワークスペースモデルが期待どおりに参照を解決できるか確認します。

特に、次のケースは移行前に検証してください。

components:
  schemas:
    User:
      $ref: "../common/schemas/user.yaml"

確認観点:

ファイル間 $ref が解決されるか
複数プロジェクトで共有スキーマを参照できるか
スキーマ更新時に影響範囲を追跡できるか

監査ログ

コンプライアンス要件がある場合は、監査ログの形式と保持期間を確認してください。

確認する内容:

スペック変更履歴
APIドキュメントの公開操作
テスト実行履歴
ユーザー権限変更
ログのエクスポート可否
保持期間

これらはApidogを避ける理由ではなく、統合プラットフォームを導入する際に必ず確認すべき実装要件です。

2つのツールを使い続けるべきケース

Apidogに集約するメリットは、仕様、モック、ドキュメント、テストを同じOpenAPIコントラクトに接続できることです。

ただし、次のような場合はStoplightとPostmanを使い続ける判断も合理的です。

Stoplight Docsの toc.json やカスタムドメイン設定が深く作り込まれている
技術ライターがStoplight中心のドキュメントワークフローを運用している
Postmanコレクションに大量の事前リクエストスクリプトがある
複雑な動的変数チェーンをPostmanで運用している
Postman Monitorを本番監視やオンコール通知に使っている

この場合は、移行コストと保守コストを比較します。

判断の目安は次のとおりです。

移行すべき可能性が高い:
仕様変更のたびにPostmanコレクションを手動更新している
QAが古いテストで失敗を調査している
OpenAPIとテストの差分確認に時間がかかっている

現状維持も検討:
Postmanスクリプト資産が大きい
Stoplight Docsの公開フローが組織に深く組み込まれている
監視・通知をPostman Monitorに強く依存している

Postman代替を広く比較したい場合は、APIテストに最適なPostmanの代替案も参考になります。

FAQ

ApidogはStoplight StudioのビジュアルOpenAPIエディタを置き換えられますか？

はい。ApidogにはOpenAPIスキーマ用のビジュアルフォームエディタがあり、リアルタイム検証とリントルールを使えます。

ただし、チームが .spectral.yaml によるカスタムSpectralルールへ強く依存している場合は、Apidog側で同等のルールをカバーできるか事前に確認してください。

Apidogは既存のGitHubリポジトリと同期できますか？

はい。Apidogのスペックファーストモードは、GitHubまたはGitLabリポジトリに接続し、OpenAPI仕様をコミットと同期します。

既存リポジトリを破棄する必要はありません。

APIスペックをGitで管理する考え方については、コードとしてのAPIスペックを参照してください。

ApidogはCIでCLIテスト実行できますか？

はい。ApidogにはCLIがあり、テストシナリオをCIで実行してレポートを出力できます。

現在 newman run を使っている場合は、Apidog CLIの実行コマンドに置き換える必要があります。NewmanのJSON出力を前提にした独自ダッシュボードがある場合は、レポート形式の違いも確認してください。

Postmanの事前リクエストスクリプトは移行できますか？

Apidogは事前リクエストスクリプトと動的変数をサポートしています。

ただし、Postmanの pm.variables.set() やカスタムJavaScriptを使っている場合、スクリプトは移植が必要です。ロジック自体は転用できることが多いですが、構文やAPIの違いは確認してください。

Apidogのスペックファーストモードは本番運用できますか？

スペックファーストモードは現在ベータ版です。

コア機能は利用できますが、次のようなケースは事前に概念実証で確認してください。

大規模モノレポ内のOpenAPI仕様
複数ファイルにまたがる $ref
ネストされたスキーマ参照
CIステータスレポート
チーム別の権限管理

本番展開前に、実際のリポジトリとAPI仕様で検証することをおすすめします。

結論

StoplightとPostmanの組み合わせは、API設計とAPIテストの両方をカバーできます。ただし、仕様とテストが別ツールに分かれるため、同期漏れ、重複メンテナンス、請求ラインの増加が発生しやすくなります。

Apidogのスペックファーストモードを使うと、Git上のOpenAPI仕様を信頼できる情報源にしたまま、ドキュメント、モック、テスト、CI実行を同じワークスペースに接続できます。

移行を検討する場合は、まず次を小さく検証してください。

既存のOpenAPIリポジトリをApidogに接続する
主要エンドポイントのモックを生成する
スキーマベースのテストを作成する
CIでApidog CLIを実行する
SSO、権限、監査ログを確認する

Apidogのスペックファーストモードを試すには、GitHubまたはGitLabからOpenAPIリポジトリを接続し、同じスペックからライブドキュメントとモックサーバーを生成します。Apidogをダウンロードして概念実証を開始するか、スペックファーストモードのページを確認してください。

Gitを諦めないOpenAPI連携：ファイルベースチームの共同作業術

Akira — Fri, 05 Jun 2026 07:22:46 +0000

OpenAPI仕様をGitで管理すると、履歴・ブランチ・PRレビューは扱いやすくなります。一方で、QA、フロントエンド、プロダクトマネージャーがAPI設計に参加するための導線は不足しがちです。Gitは仕様の置き場所として適していますが、Gitのレビューツールは基本的にコードレビュー向けであり、API仕様を「ドキュメント」として読む関係者には使いにくい場面があります。

今すぐApidogを試す

すでにOpenAPI仕様をYAMLまたはJSONとしてリポジトリに保存しているチームでは、次のような状態になりやすいです。

仕様はGitでバージョン管理されている
PRで差分レビューはできる
しかし非エンジニアはStoplightなどのプレビューを見ながらSlackで質問している
フロントエンドはバックエンド実装が終わるまで試せない
仕様変更の影響範囲がチームごとに通知されない

「api-spec-as-code」の記事では、GitをOpenAPI仕様の真のソースにする考え方を説明しています。この記事では、その後に残るコラボレーションのギャップと、ApidogのようなツールでGit中心のまま補完する方法を実装寄りに整理します。

Gitだけでは埋められないギャップ

Gitは以下を扱うには非常に強力です。

変更履歴
ブランチ
Pull Request
差分レビュー
CI/CDトリガー

しかし、OpenAPI仕様をチーム全体の作業起点にする場合、Gitだけでは不足する領域があります。

1. 非エンジニアからの設計時コメント

QAエンジニアが openapi.yaml の差分を見て、エラーレスポンスのスキーマ不整合に気づいたとします。

GitHubのPR上では、YAMLの行番号にコメントできます。ただし、API仕様をドキュメントとして読んでいる人にとっては、次のようなレビューのほうが自然です。

POST /payments に対してコメントする
422 レスポンスに対して質問する
ValidationError スキーマに対して修正依頼する
コメントをスレッド化して解決済みにする

つまり、行番号ではなく「仕様要素」に紐付いたレビューが必要です。

2. 現在のブランチに紐付くライブモック

フロントエンド開発者は、バックエンド実装が完了する前にAPIを叩きたいことがよくあります。

Gitに openapi.yaml があるだけでは、モックサーバーは自動では起動しません。たとえば手元で以下を実行する必要があります。

npx @stoplight/prism-cli mock api/openapi.yaml

これはローカル検証には便利ですが、チーム運用では次の課題が残ります。

ブランチごとにモックURLを分けたい
フロントエンドチーム全員で同じモックを使いたい
PRごとに最新仕様のモックを確認したい
本番向けドキュメントのモックURLは安定させたい

3. ロールに応じた通知ルーティング

バックエンドチームが共有仕様に破壊的変更をマージした場合、影響を受けるチームはすぐに知る必要があります。

GitのWebhookでSlack通知はできますが、多くの場合は以下のような粗い通知になります。

api/openapi.yaml が変更されました。

APIチームが必要とするのは、より具体的な通知です。

/payments のレスポンススキーマが変更されました。フロントエンド、モバイル、QAチームは確認してください。

このレベルの通知には、Gitの変更イベントだけでなく、OpenAPIのパス・タグ・スキーマを理解するレイヤーが必要です。

4. ドキュメントのアクセス制御

公開GitHubリポジトリに仕様を置くと、誰でも読めます。プライベートリポジトリにすれば制限できますが、APIドキュメントの読者ごとに細かく出し分けるのは簡単ではありません。

たとえば以下のような制御です。

外部パートナーには公開APIだけ見せる
社内QAには内部APIも見せる
管理系APIは特定チームだけに見せる
エンドポイント単位でドキュメントアクセスを分ける

Gitはソースコードのアクセス制御には向いていますが、APIドキュメントのオーディエンス制御をネイティブに提供するものではありません。

コラボレーションレイヤーの役割

実装方針はシンプルです。

Gitを真のソースにしたまま、OpenAPIファイルの上にドキュメント、モック、レビュー、通知、CI/CDレポートを重ねる。

この「コラボレーションレイヤー」を追加すると、Gitを置き換えずにチーム全体の作業体験を改善できます。

カテゴリ	例	強み	Gitの上に加えるもの
ホスト型仕様プラットフォーム	Stoplight, SwaggerHub	洗練されたUI、コメント、アクセス制御	独自の仕様コピーを保持。Gitはオプション
ファイルネイティブなコラボレーションレイヤー	Apidog Spec-Firstモード（ベータ版）, Redocly	コミットされたファイルから作業。Gitの権威性を維持	コラボレーション、モック、CIをファイルの上に追加
GitネイティブAPIクライアント	Bruno, Insomnia	ファイル同期、コレクション管理	リクエスト実行が中心。ドキュメント、モック、レポートは別途必要

ツールを選ぶときは、「Git連携があるか」だけで判断しないほうが安全です。次の観点で確認します。

OpenAPIファイルを真のソースとして扱えるか
独自コピーとの二重管理にならないか
ブランチごとにモックを作れるか
コメントが仕様要素に紐付くか
CI/CDでコントラクトテストを実行できるか
通知をパスやタグ単位でルーティングできるか
ドキュメントアクセスをロールごとに制御できるか

BrunoのGit連携は強力だが、リクエストレイヤーで止まる

BrunoはファイルネイティブなAPIクライアントとして強力です。特にBruno Ultimateは、以下のような機能を備えています。

ファイルベースのコレクション管理
Git統合
SSO
SCIM
シークレットマネージャーフック
監査ログ

主なニーズが「別途管理しているOpenAPI仕様やAPIに対してリクエストを実行すること」であれば、BrunoのGit機能は堅牢です。

ただし、Brunoの中心はリクエストレイヤーです。次のような機能は、別の仕組みが必要になります。

コミットされたOpenAPIファイルからAPIドキュメントを自動生成する
ブランチごとのモックサーバーを生成する
仕様パスの変更に応じて通知先を分ける
ドキュメントのアクセス制御を行う
コントラクトテストやレポートと仕様レビューを統合する

たとえば、すでにStoplightでドキュメントとモックを運用しているチームにBrunoを導入する場合、Stoplightを置き換えるのではなく、Brunoを並行追加する構成になります。それが適切な場合もありますが、役割分担は明確にしておくべきです。

ApidogのSpec-Firstモードでギャップを埋める

ApidogのSpec-Firstモード（現在ベータ版）は、GitにコミットされたOpenAPIファイルを権威あるソースとして扱い、その上にコラボレーション機能を重ねるためのモードです。

openapi.yaml をGitにコミットすると、Apidogはそのファイルを読み込み、仕様を独自データベースにフォークするのではなく、ファイルベースのワークフローに接続します。

実装フローは次のようになります。

ステップ1：Gitリポジトリをリンクする

Apidogでプロジェクトを作成し、GitHub、GitLab、またはBitbucketリポジトリに接続します。その後、OpenAPIファイルのパスを指定します。

接続手順は apidog-git-integration-sync ガイドで確認できます。

例として、リポジトリに次のファイルを置きます。

# api/openapi.yaml
openapi: "3.1.0"
info:
  title: 決済API
  version: "2.4.0"

paths:
  /payments:
    post:
      summary: 決済を作成
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: 決済が作成されました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "422":
          description: バリデーションエラー
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, source]
      properties:
        amount:
          type: integer
          description: 最小通貨単位での金額（例：セント）
        currency:
          type: string
          enum: [usd, eur, gbp]
        source:
          type: string
          description: 決済方法トークン

    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, completed, failed]

    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

この状態で、Git側では通常どおりPRレビューを行えます。

git checkout -b feature/payment-v2
git add api/openapi.yaml
git commit -m "Update payment API schema"
git push origin feature/payment-v2

ステップ2：差分ではなく仕様要素にコメントする

Gitにリンクされると、ApidogはOpenAPI仕様をインタラクティブなドキュメントとして表示します。

これにより、QAやフロントエンドのメンバーは、YAMLの行番号ではなく以下の単位でコメントできます。

エンドポイント
リクエストボディ
レスポンス
スキーマ
サンプル値
説明文

たとえばQAエンジニアは、POST /payments を確認しながら次のような指摘を残せます。

idempotency-key ヘッダーが必要ではありませんか？二重決済防止のため、仕様に追加してください。

エンジニアは指摘を受けて openapi.yaml を更新し、コミットします。変更がApidog側に反映されると、会話は行番号ではなく仕様要素に紐付いたまま残ります。

ステップ3：ブランチ固有のモックを生成する

Spec-Firstモードでは、仕様のブランチごとにモックサーバーを分けられます。

たとえば以下のように運用できます。

ブランチ	用途	モック
`main`	安定版仕様	QAやステージング確認用
`feature/payment-v2`	決済API改修	フロントエンド先行開発用
`feature/admin-api`	管理API追加	内部チーム検証用

これにより、フロントエンド開発者はバックエンド実装を待たずに、対象ブランチの仕様に基づくモックURLを使えます。

ローカルで毎回以下を実行する必要もありません。

npx @stoplight/prism-cli mock api/openapi.yaml

ステップ4：適切なチームに通知をルーティングする

仕様内のパスやスキーマが変更されたら、影響するチームだけに通知を送ります。

例：

変更対象	通知先
`/payments`	フロントエンド、モバイル、QA
`/admin`	内部管理ツールチーム
`ValidationError`	バックエンド、QA
認証ヘッダー	全API利用チーム

SlackやMicrosoft Teamsに通知する場合は、各プラットフォームのWebhook設定を使います。

Apidog側では、通知チャンネルをエンドポイントタグやパスプレフィックスに紐付けます。

トライアル時には、特に以下を確認してください。

タグ単位で通知できるか
パス単位で通知できるか
破壊的変更だけ通知できるか
ドキュメントのアクセス制御とチームロールを対応付けられるか

CI/CDに接続する

コラボレーションレイヤーは、チャット通知だけでなくCI/CDに接続すると実用性が上がります。

基本構成は次のとおりです。

PRでOpenAPIファイルを変更する
CIでOpenAPI仕様をLintする
コントラクトテストを実行する
失敗したらPRをブロックする
成功したらレビューとマージに進む

仕様のLintには Spectral や Redocly CLI を利用できます。Apidog CLIを組み合わせると、コントラクトテストもCIステップに含められます。

GitHub Actionsの例です。

# .github/workflows/api-spec.yml
name: API仕様の検証とテスト

on: [push, pull_request]

jobs:
  validate-and-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: OpenAPI仕様の検証 (Spectral)
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint api/openapi.yaml --ruleset .spectral.yaml

      - name: Apidogコントラクトテストの実行
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          npx apidog-cli run \
            --project-id ${{ vars.APIDOG_PROJECT_ID }} \
            --test-suite "決済APIスモークテスト" \
            --environment staging

OpenAPI仕様は、APIが約束する内容の標準的なリファレンスです。コミットされた仕様に対してコントラクトテストを実行すれば、実装が仕様から逸脱した場合にCIで検出できます。

GitネイティブなAPIワークフロー全体については、git-native-api-workflow でエンドツーエンドの構成を確認できます。

ファイルベースチーム向けの比較

ファイルベースでOpenAPIを管理する場合、主要な比較軸は「Gitを真のソースにできるか」です。

機能	Stoplight	SwaggerHub	Apidog Spec-First（ベータ版）
Gitを権威あるソースとする	オプション（デフォルトで独自コピー）	オプション	はい
設計時コメント	はい	はい	はい
ブランチ固有のモック	はい	部分的	はい
ロールベースのドキュメントアクセス	はい	はい	トライアルで確認
プロジェクト横断的なスキーマ再利用	はい	はい	トライアルで確認
CI/CDコントラクトテスト	Prism経由	限定的	はい（Apidog CLI）
カスタムLintルール	Spectral経由	限定的	トライアルで確認
SSO/SCIM	有料プラン	エンタープライズ	トライアルで確認
通知ルーティング	Webhook経由	限定的	はい
ファイルネイティブ（二重コピーなし）	いいえ	いいえ	はい（Spec-First）

SwaggerHubを含むより広い比較は、swaggerhub-vs-apidog-collaboration を参照してください。

よくある質問

ApidogのコメントとGitのPRレビューは併用できますか？

はい。用途が異なります。

GitのPRレビュー：YAML変更を確認するエンジニア向け
Apidogのコメント：仕様をドキュメントとして確認するQA、フロントエンド、PM向け

コミットされたOpenAPIファイルは、どちらのフローでも単一の真のソースとして扱えます。

Apidog上で仕様を編集した場合はどうなりますか？

Spec-Firstモードでは、Apidogインターフェースで行った編集をGitにコミットとしてプッシュバックできます。

典型的な流れは以下です。

Apidog UIで仕様を編集する
ブランチにコミットする
GitでPRを作成する
エンジニアがレビューする
マージする

ただし、チームによって「GitからApidogへ同期するだけにする」のか「ApidogからGitへも書き戻す」のかは運用方針が変わります。導入前に確認してください。

Spec-Firstモードの詳しい手順は、spec-first-mode-apidog-beta-walkthrough で確認できます。

複数のOpenAPIファイルを持つモノリポでも使えますか？

モノリポでは、サービスごとに複数のOpenAPIファイルを持つ構成が一般的です。

例：

apps/
  payments/
    api/openapi.yaml
  users/
    api/openapi.yaml
  admin/
    api/openapi.yaml

Apidogは複数プロジェクトをサポートしており、それぞれ異なるファイルパスにリンクできます。

ただし、次の点はリポジトリ構成に依存するため、トライアルで確認してください。

単一Apidogプロジェクトに複数仕様ファイルをマッピングできるか
共通スキーマを複数プロジェクトで再利用できるか
カスタムLintルールを横断的に共有できるか
ブランチごとのモックURLをサービス単位で分けられるか

Redoclyとはどう比較されますか？

Redocly CLI は、OpenAPIファイルのLint、バンドル、ドキュメント生成に強いツールです。Redoclyのホスト型プラットフォームでは、レビューやチーム機能も追加されます。

ApidogのSpec-Firstモードとの比較では、次の点を確認するとよいです。

コミット済みファイルを真のソースとして扱えるか
モック、コントラクトテスト、通知、ドキュメントを同じワークフローで扱えるか
チームメンバーが仕様要素にコメントできるか
Git上のPRレビューと競合しないか

OpenAPI Initiativeのツールはどうですか？

OpenAPI Initiative はOpenAPI仕様そのものを公開しており、コラボレーションプラットフォームを提供しているわけではありません。

ツールを選ぶ際は、利用しているOpenAPIバージョンに対応しているかを確認してください。特にOpenAPI 3.1を使う場合は、各ツールで OpenAPI 3.1 のサポート状況を検証する必要があります。

まとめ

OpenAPI仕様をGitに保存しているなら、ファイル管理の問題は解決しています。しかし、チームコラボレーションの問題はまだ残ります。

必要になるのは、Gitを置き換えるツールではなく、Gitにある仕様ファイルの上に次の機能を重ねるレイヤーです。

仕様要素に紐付くコメント
ブランチごとのモック
パスやタグに応じた通知ルーティング
ドキュメントアクセス制御
CI/CDでのLintとコントラクトテスト
非エンジニアも参加できるレビューUI

現在、Gitで仕様を管理し、Stoplightや共有ドキュメントでコラボレーションを補っているなら、それは Apidog Spec-Firstモードが統合しやすい構成です。

Spec-Firstモードはまだベータ版のため、本格導入前に以下を重点的に検証してください。

ドキュメントのアクセス制御
プロジェクト横断的なスキーマ再利用
通知ルーティングの粒度
Gitとの同期方向
CI/CDでのコントラクトテスト
既存PRレビューとの共存

Apidogをダウンロードし、既存のOpenAPI仕様リポジトリのブランチに接続して、Git中心のままコラボレーションレイヤーを追加できるか確認してください。

Postmanコレクションがソースオブトゥルースではない理由とその解決策

Akira — Fri, 05 Jun 2026 06:48:57 +0000

PostmanコレクションとOpenAPI SpecのどちらをAPI契約として扱うべきかは、チーム開発では避けて通れません。6ヶ月前のPostmanコレクションを開くと、必須フィールドが増え、非推奨パラメーターが残り、レスポンス例が実際のサーバー応答と一致しないことがあります。一方で、Git上のOpenAPI SpecやSwagger UIは別の内容を示している。こうなると、どれが正しいAPI仕様なのか判断できません。

今すぐApidogを試す

この「ずれ」はツールの不具合ではなく、ワークフローの問題です。Postmanはリクエスト実行、スクリプト、探索的テストに強いツールです。しかし、チームがPostmanコレクションをAPI契約そのものとして扱うと、OpenAPI Specやドキュメント、テストとの同期が崩れます。

💡 依存関係を逆転させ、OpenAPI Specからコレクションを生成するようにすると、ずれを防げます。ApidogはこのSpec駆動型ワークフローをコラボレーション、モック、テスト、CI/CDに接続し、チームが同じソースから作業できるようにします。

なぜコレクションは乖離するのか

Postmanコレクションは、リクエストファーストの成果物です。

通常は次の流れで作られます。

エンドポイントにリクエストを送る
レスポンスを確認する
リクエストを保存する
プリリクエストスクリプトやテストアサーションを追加する
環境変数やフォルダ構造で整理する

この構造は「今日このエンドポイントをどう呼ぶか」を表すには便利です。

一方、OpenAPI Specはコントラクトファーストの成果物です。パス、パラメーター、スキーマ、レスポンス型を機械可読な形式で定義し、検証、モック、コード生成に使えます。

つまり、両者は答える問いが違います。

Postmanコレクション: このAPIをどう呼び出すか
OpenAPI Spec: このAPIは何を満たすべきか

チームが両方を独立して更新すると、必ずずれます。

たとえば、ある開発者がPRでOpenAPI Specを更新し、別の開発者がテスト失敗を見てPostmanコレクションだけを直す。誰も両者を突き合わせない。数ヶ月後には、同じAPIに対する2つの不完全な説明が残ります。

Inventis Koreaも同様の問題を報告しています。APIを構築し、Swagger用にOpenAPI Specを生成し、テスト用にPostmanへインポートした後、3つの表現を同期させるために継続的な手作業が必要になりました。コレクションが完全なスキーマを反映していないため、テストはエッジケースを見逃し、Specがテスト作成の入力ではないため、ドキュメントも乖離しました。

根本原因：PostmanはSpecストアではない

Postmanコレクションには独自フォーマットがあります。Postmanコレクションスキーマは、リクエスト、スクリプト、フォルダ階層を記述するJSON構造です。

これはOpenAPIではありません。

PostmanはOpenAPIをインポート・エクスポートできますが、変換には情報の欠落が発生します。

OpenAPI → Postmanコレクションリクエストとして表現できないスキーマ情報が失われることがある
Postmanコレクション → OpenAPI スクリプトや実行時データなど、Specに表現できない情報が失われる

これはPostmanへの批判ではありません。Postmanはリクエストランナーであり、探索的テストやスクリプト実行に適したツールです。しかし、正規のAPI契約ストアとして使うには限界があります。

プロパティ	Postmanコレクション	OpenAPI Spec
リクエストパラメータ	オプションの説明付きキーと値のペアとして保存	型指定され、`required` や `schema` で検証可能
レスポンスの形状	保存された例としてキャプチャされる	JSON Schemaとして定義され、`$ref` で再利用可能
エラーレスポンス	リクエストごとに手動追加	`responses` と `components/schemas` で列挙
スキーマの再利用	基本的にコピー＆ペースト	`$ref` により再利用
機械可読な契約	いいえ	はい。サーバー、クライアント、モック生成に利用可能
Git diff	不透明なIDを含むJSONでレビューしづらい	YAMLで行単位の差分を確認しやすい
Lintと検証	ネイティブ形式では難しい	Spectral、Redocly CLIなどで可能

コレクションはAPI契約を完全に表現できません。そのため、契約は別の場所に存在する必要があります。問題は、その「別の場所」とコレクションを手動で同期しようとすることです。

PostmanチームにとってのSpecファーストとは

Specファーストとは、必ずしも「コードを書く前にすべてをYAMLで設計する」という意味ではありません。

Postman中心のワークフローから移行するチームにとっては、依存関係を逆転させることです。

Specファーストの方法論では、OpenAPIドキュメントをAPIの信頼できる記述としてGitに置きます。テスト、モック、ドキュメント、Postmanコレクションは、そのSpecから派生させます。

実装上の流れは次のとおりです。

OpenAPI SpecをGitにコミットする
PRでSpec変更をレビューする
CIでSpecをlint・検証する
Specからモック、ドキュメント、テスト、コレクションを生成する
API変更時はまずSpecを変更する
下流の成果物を自動生成または同期する

コレクションは引き続き使えます。スクリプト、データ駆動型テスト、環境変数も残せます。

違いは、コレクションをSpecの上流に置かないことです。

Specに新しいフィールドが追加されると、生成されたコレクションにも反映されます。Specからフィールドが削除されると、生成されたリクエストからも消えるため、テストが失敗します。ずれは6ヶ月後ではなく、CIで検出されます。

SpecからPostmanコレクションを生成する

OpenAPI SpecからPostman互換コレクションを生成するには、Redocly CLIとopenapi-to-postmanv2を使えます。

# Redocly CLIをインストール
npm install -g @redocly/cli

# Specを検証
redocly lint openapi/petstore.yaml

# $refを解決してbundleを作成
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml

# openapi-to-postmanv2をインストール
npm install -g openapi-to-postmanv2

# Postman collection v2.1に変換
openapi2postmanv2 \
  --spec dist/petstore-bundled.yaml \
  --output dist/petstore-collection.json \
  --prettyPrint

生成されるのは標準のPostmanコレクションJSONです。Postmanにインポートすることも、NewmanやPostman CLIで実行することもできます。

プリリクエストスクリプトや環境変数は、別ファイルとして管理します。Specからコレクションを再生成しても、それらを上書きしない構成にします。

GitHub ActionsでSpec生成とテストを自動化する

CIに組み込むと、テスト実行前に常にSpecからコレクションを再生成できます。

# .github/workflows/api-tests.yml
name: API contract tests

on:
  push:
    paths:
      - "openapi/**"
      - "src/**"

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          npm install -g @redocly/cli openapi-to-postmanv2 newman

      - name: Validate OpenAPI spec
        run: redocly lint openapi/petstore.yaml

      - name: Generate collection from spec
        run: |
          mkdir -p dist
          redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
          openapi2postmanv2 \
            --spec dist/petstore-bundled.yaml \
            --output dist/petstore-collection.json

      - name: Run tests against generated collection
        run: |
          mkdir -p results
          newman run dist/petstore-collection.json \
            --environment config/env-staging.json \
            --reporters cli,junit \
            --reporter-junit-export results/test-results.xml

      - name: Upload test results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results/

この構成では、Specがすべてのテスト実行の入力になります。

Spec変更によってテストが壊れる場合、その変更を入れたPRで検出できます。Postmanコレクションを手動更新する必要はありません。

Apidogをこのワークフローで使う位置づけ

Apidogの役割は、Postmanを単純に置き換えることではありません。

OpenAPI Specと、チームが使うモック、ドキュメント、テスト、コラボレーション機能を接続する実行レイヤーとして使えます。Git内のSpecを信頼できる情報源にし、その上にApidogのワークスペースを構築します。

ApidogのSpec-Firstモード（現在ベータ版）では、GitリポジトリからOpenAPI SpecをApidogワークスペースに同期できます。

同期されたSpecから、次の成果物を扱えます。

自動生成されたモック
インタラクティブなAPIドキュメント
テストシナリオ
チーム向けの共有ワークスペース

SpecがGitで変更されると、Apidog上の内容も同期されます。Specと並行して別のコレクションを手動で管理する必要はありません。

これは、STCグループや世界経済フォーラムが指摘したような構成で特に重要です。

テスト用にPostmanを使う
Specレンダリング用に別のドキュメントツールを使う
フロントエンド開発用にモックサーバーを使う
それぞれが同じAPI契約を反映する必要がある

Specを1箇所で更新し、そこから各インターフェースを更新できれば、同期コストを大きく減らせます。

既存資産から始める場合は、PostmanコレクションをApidogに変換して出発点にできます。その後、OpenAPI Specを正規のドキュメントとして運用します。

GitワークフローでSpecをコードとして扱う

API Spec as Codeアプローチでは、OpenAPIドキュメントをアプリケーションコードと同じように扱います。

具体的には次のようにします。

Pull Requestで変更する
コードレビューする
CIでlintする
リリース時にバージョンタグを付ける
破壊的変更をブランチで管理する

多くのチームは、すでにこのためのGitインフラを持っています。必要なのは、それをSpecファイルにも適用することです。

実践しやすいルールは次のとおりです。

Specはサービスと同じリポジトリに置く

別のdocsリポジトリに分離すると、コード変更とSpec変更が別PRになりやすくなります。
CIにSpectralを追加する

SpectralはOpenAPI仕様とカスタムルールに対してSpecを検証できます。
壊れた$refや説明漏れをCI失敗にする

レビューコメントで人間が見つけるのではなく、自動検出します。
破壊的変更はブランチで管理する

アプリケーションコードと同様に、安定ブランチと変更ブランチを分けます。
下流のコンシューマーはSpecバージョンを固定する

サービスBがサービスAのSpecを契約テストに使う場合、mainのHEADではなく、特定のタグを参照します。

新しいプロジェクトでのセットアップ例は、git-native APIワークフローガイドで詳しく説明されています。

FAQ

Postmanの使用を完全にやめる必要がありますか？

いいえ。

変更するのはツールではなく、依存関係の方向です。探索的テストやスクリプト作成にはPostmanを使い続けられます。

ただし、コレクションを個別に保守するのではなく、各テスト実行前にSpecから生成します。Postman UIを使う運用と、Specファーストのワークフローは両立できます。

既存のPostmanスクリプトと環境変数はどうなりますか？

プリリクエストスクリプト、テストスクリプト、環境変数は、生成されたコレクションとは別ファイルで管理します。

リクエスト定義: OpenAPI Specから生成
実行時の挙動: スクリプトや環境変数として維持

この分離により、Specからコレクションを再生成しても、既存のスクリプトを上書きせずに済みます。

まだSpecにないエンドポイントはどう扱いますか？

Specファーストのワークフローでは、Specにないエンドポイントはテスト対象として準備完了ではありません。

これは制約ではなく、ゲートとして機能します。新しいエンドポイントを追加するPRでは、実装と同じPRでSpecエントリも追加します。

探索的開発では、ローカルスタブに対して作業し、正式に導入するタイミングでSpecに反映します。編集や検証を高速化したい場合は、最高のOpenAPIバリデータツールを参考にできます。

Apidog Spec-Firstモードは現在利用可能ですか？

Apidog Spec-Firstモードは現在ベータ版です。

Apidogからアクセスし、Git同期ワークフロー、ブランチサポート、自動生成モックがチームの要件に合うか検証できます。

ベータ機能のため、本番ワークフローに組み込む前に、自分たちのOpenAPI Spec構造で試すことをおすすめします。

SpecをPostmanにインポートするだけでは不十分ですか？

PostmanはOpenAPI Specをインポートし、そこからコレクションを生成できます。

ただし、それは一度限りの変換です。その後、コレクションを手動で編集し始めると、Specとの乖離が再び発生します。

Specファーストのワークフローでは、CI実行や同期のたびにSpecからコレクションを再生成します。そのため、コレクションがSpecより古くなることを防げます。

結論

PostmanコレクションとOpenAPI Specの乖離は、Postmanのバグではありません。部分的に重複する2つのAPI記述を、明確な依存関係なしに維持することの結果です。

解決策はシンプルです。

Git内のOpenAPI Specを信頼できる情報源にする
PostmanコレクションをSpecの下流成果物として生成する
CIでSpec検証とコレクション生成を自動化する
ドキュメント、モック、テストを同じSpecから派生させる

この構成にすると、壊れるタイミングが変わります。Spec変更によってテストが壊れる場合、そのPR内で検出できます。ドキュメント、モック、テストシナリオは同じソースを参照するため、手動同期の負担が減ります。

Apidogをダウンロードし、既存のOpenAPI SpecでSpec-Firstモードのワークスペースを試してください。コレクションから始める場合は、PostmanコレクションをOpenAPIの出発点としてインポートし、そこからSpecファーストの運用に切り替えられます。

SwaggerドキュメントとPostmanコレクションが乖離してしまう原因と解決策

Akira — Fri, 05 Jun 2026 06:21:12 +0000

SwaggerとPostmanの乖離は、レビュー不足ではなく、同じAPI契約を2つの成果物として管理していることが原因です。openapi.yamlでSwagger UIを生成し、Postmanコレクションでテストを実行すると、どちらか一方だけが更新された瞬間にドキュメントとテストが別物になります。この記事では、なぜ乖離が構造的に発生するのか、そしてOpenAPIを単一の情報源としてドキュメント・モック・テストを運用する手順を説明します。仕様からテストを生成する具体的な手順は、OpenAPIテスト生成に関する既存のハウツーを参照してください。

今すぐApidogを試す

💡 Apidogを使用しているチームは、OpenAPIファイルをドキュメント、モック、テストを同時に駆動する単一の成果物として扱います。解決策は、より厳格なレビューではなく、乖離する可能性のある2つ目の成果物をなくすことです。

なぜ2つのファイルは常に乖離するのか

多くのチームは、次の2つを別々に管理しています。

Git上のopenapi.yaml
テスト用のPostmanコレクション

どちらも同じAPI契約を表すはずですが、保存場所、編集者、更新タイミングが異なります。どちらのツールも、もう一方との整合性を強制しません。

例を見てみます。

バックエンドチームが、必須のreasonフィールドを持つ新しいPOST /payments/refundエンドポイントをリリースします。QAまたはバックエンド開発者は、テストを実行するためにPostmanコレクションへエンドポイントを追加します。一方、openapi.yamlの更新は後回しになります。

数日後、フロントエンド開発者はSwagger UIのドキュメントを見て、reasonなしでAPIを呼び出します。その結果、ドキュメント上は説明されていない400エラーが返ります。

これは怠慢ではありません。根本原因は、2つの成果物の間に結合がないことです。

成果物	更新者	更新トリガー	検証
`openapi.yaml`	APIデザイナー / テックリード	計画されたドキュメント更新	オプションのリンター（例: Spectral）
Postmanコレクション	QA / バックエンド開発者	テスト実行が必要なとき	手動レビューまたはなし
Swagger UI表示	YAMLから自動レンダリング	YAMLがプッシュされたときのみ	実際のAPIではなくYAMLを反映

Rulesets - Spectralのようなリンターを使えば、OpenAPI仕様内の構文やスキーマ上の問題は検出できます。しかし、Postmanコレクションが別のリクエストを送信しているかどうかは検出できません。

3つのコピー問題

Stoplight、Swagger UI、Wikiなどのドキュメント基盤も併用している場合、API契約のコピーはさらに増えます。

Gitにコミットされたopenapi.yaml
エクスポート・共有されたPostmanコレクション
Stoplight、Swagger UI、Wikiなどで表示されるドキュメント

それぞれが独立して更新されるため、それぞれが乖離ポイントになります。

OpenAPI Specificationは、APIを記述するための仕様です。同期プロトコルではありません。OpenAPIファイルに書いた内容と、Postmanコレクションで送信している内容が一致することを自動的に保証する仕組みはありません。

同じ契約を3か所で管理すると、障害点も3つになります。サービス数やチーム規模が大きくなるほど、手動同期のコストは非線形に増えます。

乖離がテストを静かに壊す方法

SwaggerとPostmanの乖離で厄介なのは、テストが間違っていても成功し続けることです。

たとえば、OpenAPI仕様では必須フィールドが追加されたのに、Postmanコレクションが古いリクエストボディを送り続けるケースです。バックエンドが移行期間中に古い形式も受け入れている場合、Postmanテストは成功します。しかし、その成功は現在の仕様を検証していることを意味しません。

以下は、仕様側でreasonが必須になった例です。

# openapi.yaml - 更新された仕様 (v2)
paths:
  /payments/refund:
    post:
      summary: 返金を申請する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_id
                - reason          # v2で追加された新しい必須フィールド
              properties:
                transaction_id:
                  type: string
                  example: "txn_8x9Ka21"
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]
                  example: "requested_by_customer"
      responses:
        '200':
          description: 返金が開始されました
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund_id:
                    type: string
                  status:
                    type: string

古いPostmanコレクションは、次のようにtransaction_idだけを送る可能性があります。

{
  "transaction_id": "txn_8x9Ka21"
}

バックエンドがreasonにデフォルト値を補完している場合、このテストは成功します。しかし、仕様上はreasonが必須です。フロントエンドが仕様を見て実装したとき、または別の環境で厳密なバリデーションが有効になったときに問題が表面化します。

OpenAPIバリデーターは、仕様内の不整合を検出できます。しかし、仕様とPostmanコレクションが実際に送信するリクエストの差分までは検出できません。

OpenAPI駆動型テストが実際に意味するもの

OpenAPI駆動型テストでは、OpenAPI仕様を信頼できる唯一の情報源として扱います。

つまり、テストは仕様と並行して手書きするのではなく、仕様から派生させます。仕様が変更されると、テストも同じ情報源を参照するため、変更を追跡できます。

これは単に「SwaggerをPostmanにインポートする」こととは異なります。インポートは一度限りのコピー操作です。インポート直後は同期していても、その後のopenapi.yaml変更はPostmanコレクションへ自動反映されません。

仕様ファーストな実行フローは次のようになります。

openapi.yamlを正式なAPI契約としてGitに置く
ツールがそのファイルを読み取る
同じ仕様からドキュメント、モック、テストケースを生成する
仕様変更はPRレビューで管理する
仕様が変更されたら、下流の出力も同じ仕様から更新する
同期対象となる別個のPostmanコレクションを持たない

仕様ファーストのAPI開発では、より広い設計ワークフローを説明しています。この記事では、特にドキュメントとテスト間の乖離に焦点を当てます。

単一の仕様上の実行レイヤーとしてのApidog

Apidogのモデルでは、Git上のOpenAPIファイルを唯一の情報源とし、Apidogをその上の実行レイヤーとして使用します。

基本的な流れは次のとおりです。

openapi.yamlをGitにコミットする
Apidogに仕様を読み込ませる
同じファイルから以下を生成する
- インタラクティブなAPIドキュメント
- モックサーバー
- テストスイート
仕様変更時は、OpenAPIファイルを更新する
下流のドキュメント、モック、テストを同じ仕様から更新する

Apidogの仕様ファーストモード（現在ベータ版）は、このワークフローのために設計されています。個別のコレクションを維持するのではなく、OpenAPIファイルを中心に出力を生成します。

結果として、乖離するPostmanコレクションを持たずに済みます。ファイルは1つだけです。OpenAPI仕様同期ワークフローでは、GitHubに仕様をコミットし、Apidogと整合させる方法を説明しています。

Postman中心のワークフローから移行する場合は、いきなり全体を置き換えるよりも、POCで次の点を検証すると安全です。

既存のスキーマ複雑度をApidogが扱えるか
データ駆動型テストシナリオを再現できるか
レポートの可視性や権限が組織のアクセスモデルに合うか
CI/CDで既存のテスト実行フローに組み込めるか

APIモックも重要です。モックがテストと同じ仕様から派生していれば、フロントエンド開発者が受け取るレスポンスと、テストが検証するレスポンスが一致します。モックの使いどころは、APIモックのユースケースを参照してください。

移行パスの概要

Swagger + Postmanの構成から移行する場合、一括置換ではなく段階的に進めます。

1. 現在の仕様とPostmanコレクションを棚卸しする

まず、openapi.yamlとPostmanコレクションを比較します。

確認する項目は次のとおりです。

仕様に存在するが、Postmanコレクションにないエンドポイント
Postmanコレクションに存在するが、仕様にないエンドポイント
HTTPメソッドの差分
必須フィールドの差分
リクエストボディスキーマの差分
レスポンススキーマの差分
認証方式の差分

このステップで、実際にどれだけ乖離しているかが見えます。

2. `openapi.yaml`を現在のAPI実装に合わせる

次に、OpenAPI仕様を現在の実装に合わせます。

重要なのは、「最初に設計したAPI」ではなく「現在動いているAPI」を記述することです。古い仕様をそのまま単一の情報源にしても、乖離の起点が変わるだけです。

3. 仕様をApidogにインポートする

整合済みのOpenAPI仕様をApidogにインポートします。

ここで、仕様構造から初期テストスイート、ドキュメント、モックを生成します。最初の目的は、既存Postmanコレクションを完全再現することではなく、仕様を中心にした実行レイヤーを作ることです。

4. 1スプリントだけ並行実行する

既存のPostmanコレクションと、Apidogで生成したテストを1スプリント並行して実行します。

比較するポイントは次のとおりです。

失敗するテストの差分
カバーされるエンドポイントの差分
リクエストペイロードの差分
認証・環境変数の扱い
レポートの見やすさ
CI実行時の運用負荷

5. Postmanコレクションを段階的に非推奨にする

並行実行で問題が解消できたら、Postmanコレクションを回帰テストの唯一の情報源として使うのをやめます。

最終的には、次の状態を目指します。

Git上のopenapi.yamlが唯一の情報源
Apidogがドキュメント、モック、テストを生成
Postmanは必要に応じて探索的テストに限定
回帰テスト用の契約はOpenAPI仕様から派生

仕様から初期テストコレクションを生成する手順は、OpenAPI仕様からのテストコレクション生成で詳しく説明されています。

比較: デュアルメンテナンス vs. 仕様を情報源とするモデル

側面	Swagger + Postman（デュアルメンテナンス）	OpenAPI駆動型（仕様を情報源とする）
乖離のリスク	高い。2つの成果物が独立して更新される	低い。1つの仕様から出力を派生
テストカバレッジの正確性	手動同期の運用に依存	仕様変更を追跡しやすい
新規開発者のオンボーディング	2つのツールと同期ルールを学ぶ必要がある	1つの仕様を中心に理解できる
CI/CD連携	コレクションのエクスポートと管理が必要	Git内の仕様を直接参照しやすい
モックの一貫性	モックを別途維持または再インポートする必要がある	テストと同じ仕様から派生
スキーマ変更のコスト	仕様、コレクション、モックをそれぞれ更新	仕様を一度更新

これはPostman自体の問題ではありません。Postmanはコレクションベースのテストや探索的なAPI呼び出しに強みがあります。問題は、Postmanコレクションを派生成果物ではなく、OpenAPI仕様と並行する契約として扱うワークフローです。

よくある質問

なぜSwaggerをPostmanにインポートしても乖離は解決しないのか？

インポートは、その時点のコピーを作るだけです。

インポート後、openapi.yamlとPostmanコレクションは独立した成果物になります。仕様が変更されるたびに再インポートするか、Postmanコレクションを手動編集する必要があります。これはデュアルメンテナンスの問題に戻ることを意味します。

仕様ファーストモデルを採用しながら、探索的テストのためにPostmanを使い続けることはできますか？

はい。仕様ファーストは、Postmanの使用を禁止するものではありません。

おすすめは、役割を分けることです。

回帰テスト・契約テスト: OpenAPI仕様から派生
一度限りの探索的呼び出し: Postmanなどを利用可能

重要なのは、探索的なPostmanコレクションをAPI契約の唯一の情報源としてコミットしないことです。

いつ自分の仕様が実際のAPI実装から乖離したかをどうやって知るのですか？

最も信頼できる方法は、契約テストレイヤーを用意することです。

APIサーバーのテスト時に、着信リクエストと発信レスポンスをOpenAPI仕様に対して検証します。Spectralのようなツールは仕様の内部整合性を検査できますが、実装との乖離を検出するにはランタイム検証が必要です。

SwaggerとPostmanの乖離、仕様と実装の乖離は別の問題です。ただし両方が同時に存在すると、原因の切り分けがさらに難しくなります。

ApidogはPostmanを完全に置き換えるのですか？

チームのワークフローによります。

Apidogは、設計、モック、テスト、ドキュメントを単一のワークスペースで扱います。Postmanの主な用途が契約テストや回帰テストスイートであれば、Apidogでその領域をカバーできます。

一方、CIでPostmanのコレクションランナーを使っている場合や、既存のコレクションスクリプトが大量にある場合は、仕様ファーストの設計ワークフローと並行してPostmanでのテストを続ける選択肢もあります。まずは1スプリントのトライアルで比較するのが現実的です。

もし`openapi.yaml`が既に古くなっていたらどうなりますか？

まず仕様を修正する必要があります。

古いopenapi.yamlを唯一の情報源にしても、間違った情報源を中心に運用するだけです。現在のAPI実装と仕様を比較し、実際の挙動を反映するようにYAMLを更新してください。

移行パスの最初の棚卸しステップは、この作業のためにあります。

結論

SwaggerドキュメントとPostmanコレクションが乖離するのは、それらが結合されていない2つの成果物だからです。これはチームの規律ではなく、デュアルメンテナンスワークフローの構造的な問題です。

解決策は、API契約を1つにすることです。

Gitにopenapi.yamlを置く
それを唯一の情報源として扱う
ドキュメント、モック、テストを同じ仕様から生成する
並行して管理するPostmanコレクションを契約の情報源にしない

Apidogをダウンロードし、既存のOpenAPI仕様をインポートしてください。1つのファイルからドキュメント、モック、テストを生成することで、SwaggerドキュメントとPostmanコレクションを別々に同期する運用を減らせます。仕様ファーストモード（現在ベータ版）を評価する場合は、現在の機能範囲とアクセス詳細をApidog仕様ファーストモードのページで確認してください。

AIエージェントデバッガーとは

Akira — Thu, 04 Jun 2026 10:40:29 +0000

AI Agent Debuggerは、AIエージェントを構築する開発者向けの視覚的なデバッグツールです。モデルの入力・出力だけでなく、対話ラウンド、モデル呼び出し、ツール呼び出し、エラー、トークン消費など、エージェントの実行プロセス全体をトレースとして確認できます。

今すぐApidogを試す

AIエージェントを実装していて、次のような疑問を持ったことがあるなら、AI Agent Debuggerが役立ちます。

なぜそのツールを呼び出したのか？
なぜ応答に時間がかかったのか？
なぜトークンを大量に消費したのか？
どのステップで失敗したのか？

AIエージェントのデバッグが難しい理由

AIエージェントの不具合は、通常のアプリケーションのバグよりも原因を特定しにくいことがあります。主な理由は次のとおりです。

1. 非決定的な動作

LLMは本質的に非決定的です。同じプロンプトでも、実行するたびに異なる出力やツール選択が発生する可能性があります。

そのため、次のような問題が起きます。

テストでは成功したが、本番では失敗する
同じ入力でもツール呼び出し順が変わる
エラーが再現しにくい

2. 長い推論チェーン

AIエージェントは、単にテキストを生成するだけではありません。

計画する
推論する
ツールを呼び出す
結果を解釈する
次のアクションを決める

10ステップのワークフローでステップ3に原因があっても、最終的な失敗はステップ10で表面化することがあります。実行トレースがなければ、根本原因の特定は困難です。

3. ブラックボックス問題

従来のコードのように、LLM内部にブレークポイントを置いて変数を検査することはできません。

確認できるのは主に次の情報です。

モデルに渡したプロンプト
モデルから返ってきた出力
ツール呼び出しの入力と出力
実行時間やトークン使用量

AI Agent Debuggerは、これらの観測可能な情報を整理して表示します。

4. ツール使用の複雑さ

エージェントが外部APIやMCPツールを呼び出す場合、失敗要因は増えます。

間違ったツールを選択した
パラメーター形式が不正だった
認証情報が不足していた
ツール自体がエラーを返した
MCPサーバーが接続されていなかった

ツール呼び出しを1つずつ確認できなければ、デバッグは当て推量になります。

5. エラーの帰属が難しい

問題の原因は、次のどこかにあります。

プロンプト
モデル
ツール
MCPサーバー
認証設定
オーケストレーションロジック

AI Agent Debuggerは、実行トレースを可視化することで、原因箇所の切り分けを支援します。

AI Agent Debuggerで確認できること

AI Agent Debuggerは、エージェントの実行を構造化されたトレースとして表示します。

完全な実行トレース

確認できる主な項目は次のとおりです。

ユーザープロンプトとシステムプロンプト

モデルに送信された正確な入力を確認できます。
モデル呼び出し

LLMへの各リクエストとレスポンスを確認できます。
思考プロセス

モデルが拡張思考をサポートしている場合、推論チェーンを確認できます。
ツール呼び出し

エージェントが呼び出したMCPツールや組み込み関数を確認できます。
ツール入力と出力

渡されたパラメーターと返された結果を確認できます。
エラーと例外

どこで何が失敗したかを確認できます。
最終出力

エージェントが最終的に生成したレスポンスを確認できます。

セッションメトリクス

実行ごとに、次のようなメトリクスを確認できます。

応答時間: 各ステップにかかった時間
トークン消費: 入力トークン、出力トークン、キャッシュ済みトークン
推定コスト: セッションごとの推定費用
対話ラウンド: 実行中のやり取り回数
実行ステップ: 実行された操作数

モデル比較

同じタスクを異なるモデルで実行し、次の観点で比較できます。

どちらのモデルが少ないステップで完了したか
どちらのモデルが適切なツールを選択したか
どちらのモデルが低レイテンシだったか
どちらのモデルが低コストだったか

AI Agent Debuggerの主なユースケース

1. ツール呼び出しチェーンのデバッグ

エージェントが予期しないツールを呼び出した場合、AI Agent Debuggerで次を確認します。

どのツールが呼び出されたか
どの順序で呼び出されたか
各ツールに渡されたパラメーター
各ツールの戻り値
どのステップで失敗したか

これは、ツール統合の問題が発生しやすいMCP（Model Context Protocol）サーバーを使うエージェントで特に重要です。

2. モデルパフォーマンスの比較

すべてのモデルがすべてのタスクに最適とは限りません。AI Agent Debuggerを使うと、同じプロンプトを複数モデルで実行して比較できます。

比較ポイント:

トークン消費
推定コスト
応答時間
ツール選択の正確性
最終出力の品質

3. トークン消費の最適化

使用量ベースの課金では、トークンの可視化が重要です。

AI Agent Debuggerでは、次のような最適化に使えます。

不要なコンテキストを含む肥大化したプロンプトを見つける
冗長な出力を短縮する
セッション間でトークン使用量を比較する
モデルやプロンプト変更によるコスト差を確認する

4. MCPサーバー統合の検証

MCPを使うと、エージェントは外部ツールやデータソースに接続できます。AI Agent Debuggerでは次を確認できます。

MCPサーバーが接続されているか
ツールが正しく公開されているか
認証が機能しているか
ツールのレスポンスが正しく解析されているか

5. システムプロンプトの反復改善

システムプロンプトの小さな変更でも、エージェントの動作は大きく変わることがあります。

AI Agent Debuggerを使うと、次の手順で改善できます。

システムプロンプトのバリエーションを作る
同じ入力で実行する
ツール選択、ステップ数、トークン消費を比較する
安定して期待通りに動くプロンプトを採用する

ステップバイステップガイド：ApidogのAI Agent Debuggerの使い方

Apidogには、前述の機能を備えた組み込みのAI Agent Debuggerがあります。

以下では、基本的な使い方をステップごとに説明します。

ステップ1：新しいエージェントデバッグセッションを作成する

Apidogデスクトップクライアントを開きます。
上部のタブバーから AI Agent Debugger に移動します。
上部セクションでモデルを設定します。

設定項目:

左: モデルプロバイダーを選択します。例: OpenAI、Anthropic
中央: モデルを選択します。例: gpt-4o、claude-sonnet-4-6
ベースURL: プロバイダーの選択に基づいて自動的に一致します

ステップ2：プロンプトを設定する

プロンプト タブをクリックし、エージェントの入力を設定します。

ユーザープロンプトの例

有効なJSONペイロードを送信したときに、POST /usersエンドポイントが500を返すのはなぜですか？

システムプロンプトの例

あなたは、開発者がAPIの問題をデバッグするのを助けるコードアシスタントです。
利用可能なツールを使用して、API応答を取得し、ドキュメントを検索し、
実行可能な解決策を提供してください。

設定できる項目:

送信後にクリア: 送信後に入力ボックスを自動的にクリアする
ユーザープロンプト: 今回のテスト入力
システムプロンプト: エージェントの役割、制約、ツール使用ルール

ステップ3：利用可能なツールを設定する

ツール タブをクリックし、エージェントが使用できるツールを選択します。

組み込みツール

Apidogは、すぐに使える組み込みツールを提供します。

ツール	機能
`bash`	永続的なシェルセッションでコマンドを実行する
`web_fetch`	ウェブコンテンツを取得し、Markdown、テキスト、HTMLに変換する
`read`	テキスト、画像、PDFファイルを読み込む
`edit`	ファイルに対して正確な文字列置換を実行する
`write`	ファイルを作成または上書きする
`grep`	正規表現を使用してファイル内容を検索する
`glob`	globパターンを使用してファイルを検索する
`kill_shell`	現在のシェルセッションをリセットする

エージェントに必要なツールだけを有効化します。無効化したツールは実行中に使用できません。

MCPツールを追加する

MCP（Model Context Protocol）経由で外部ツールを接続する手順は次のとおりです。

ツール タブで MCPサーバーを追加 をクリックします。
接続方法を選択します。
- STDIO: ローカルMCPサーバープロセスを起動する
- HTTP: ストリーマブルHTTP経由でMCPサーバーに接続する
- SSE: Server-Sent Events経由で接続する
必要に応じて認証を設定します。
- リクエストヘッダー
- OAuth 2.0認証
接続に成功したら、エージェントに公開するツールを選択します。

ステップ4：スキルを設定する（オプション）

スキル タブをクリックして、エージェントに再利用可能なスキルを追加します。

スキルは次の用途に向いています。

プロジェクト内で固定されたワークフローを提供する
一般的なタスクの操作仕様を再利用する
システムプロンプト内の重複説明を減らす

実行中、関連するスキルはタスクに応じてロードされます。

ステップ5：認証とモデルパラメーターを設定する

認証タブ

モデルサービスやMCPサービスが必要とする認証情報を追加します。

例:

APIキー
OAuthトークン
リクエストヘッダー

設定タブ

モデルの実行時パラメーターを設定します。

Temperature: ランダム性を制御する。0はより決定的、1はより創造的
Max Tokens: 最大応答長
Top P: 核サンプリングパラメーター
その他のパラメーターはモデルプロバイダーによって異なります

ステップ6：実行してトレースを確認する

右上の実行をクリックしてデバッグを開始します。

実行後、主に3つのパネルを確認します。

セッションリスト（左パネル）

各実行はセッションとして保存されます。

例:

Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-4o

別のセッションをクリックすると、過去の実行と比較できます。

ターンパネル（中央）

複数ラウンドの対話を表示します。

エージェントが複数回やり取りした場合、各ラウンドがここに表示されます。任意のターンをクリックして、そのターンの詳細トレースを確認します。

トレースパネル（右）

トレースパネルでは、エージェントの完全な実行プロセスを順番に確認できます。

確認する項目:

プロンプト: 送信されたユーザープロンプトとシステムプロンプト
モデル呼び出し: LLMリクエストとレスポンス
思考プロセス: モデルの推論情報（サポートされている場合）
ツール呼び出し: 実行されたMCPツールやカスタムスキル
ツール詳細: 入力パラメーター、結果、タイミング、エラー
最終出力: エージェントが生成した回答

ステップ7：失敗したツール呼び出しをデバッグする

問題が発生した場合は、トレースパネルで失敗したステップを確認します。

チェック手順:

トレース内で失敗したステップを見つける
入力パラメーターを確認する
ツールの出力結果を確認する
エラーメッセージを確認する
必要に応じてプロンプト、ツール設定、認証設定を修正する

よくある失敗原因:

MCPサーバーが接続されていない
MCPサーバーが途中で切断された
パラメーター形式がツール仕様と一致しない
OAuth、APIキー、ヘッダーなどの認証設定が正しくない
ローカルSTDIOサービスの起動コマンドが利用できない

ステップ8：モデルパフォーマンスを比較する

ユースケースに最適なモデルを選ぶには、同じ条件で複数モデルを実行します。

手順:

同じプロンプトを用意する
同じツール構成を使う
モデルA で実行する。例: GPT-4o
モデルB で実行する。例: Claude Sonnet
セッションを比較する

比較する項目:

どちらが少ないステップで完了したか
どちらが適切なツールを選択したか
どちらが低レイテンシだったか
どちらが少ないトークンを消費したか
どちらが低コストだったか
どちらの最終出力が期待に近かったか

AI Agent Debuggerと従来のデバッグの比較

側面	従来のデバッグ	AI Agent Debugger
焦点	コードロジック、変数、コールスタック	モデル呼び出し、ツール呼び出し、プロンプト
可視性	コードを1行ずつステップ実行	完全な実行トレースを表示
非決定性	コードは再現可能	複数の実行を比較し、パターンを見つける
ブラックボックス	変数を検査可能	モデルの入力・出力を確認する
ツール統合	各APIを個別にデバッグ	すべてのツール呼び出しを1つのトレースで確認
コストの可視性	N/A	トークン消費と推定コストを確認

よくある質問

なぜエージェントは期待したツールを呼び出さなかったのですか？

次を確認してください。

ツールは ツール タブで有効になっていますか？
システムプロンプトで、そのツールをいつ使うべきか明確に書いていますか？
MCPサーバーは接続されていますか？
対象ツールが無効化されていませんか？
トレースに思考プロセスやツール呼び出し記録がありますか？
使用しているモデルはツール呼び出しをサポートしていますか？

MCPツール呼び出しが失敗します。何を確認すべきですか？

トレースパネルで、失敗したツール呼び出しを確認します。

重点的に見る項目:

入力パラメーター: ツール仕様に合った形式か
出力結果: ツールが返したエラー内容
接続ステータス: MCPサーバーが接続中か
認証: APIキー、OAuthトークン、ヘッダーが正しいか
STDIOコマンド: ローカルサーバー起動コマンドが有効か

なぜ同じタスクを複数回実行するのですか？

AIエージェントは非決定的です。同じプロンプトでも異なる実行パスを取ることがあります。

複数回実行すると、次を確認できます。

動作のばらつき
実行ステップの違い
ツール選択の安定性
トークン消費の差
Temperatureやプロンプト変更の影響

始めましょう

AI Agent Debuggerは、API開発プラットフォームであるApidogで利用できます。

始める手順:

最新のApidogデスクトップクライアントをダウンロード
上部タブから AI Agent Debugger に移動する
モデル、プロンプト、ツールを設定する
エージェントを実行する
トレースパネルで各ステップを確認する
必要に応じてプロンプト、ツール、認証、モデルを調整する

結論

AI Agent Debuggerは、AIエージェント開発を当て推量から体系的なデバッグ作業へ変えます。

エージェントが予期しない動作をしたとき、推測するのではなく、次を確認できます。

どのプロンプトが送信されたか
どのモデル呼び出しが発生したか
どのツールが呼び出されたか
どのパラメーターが渡されたか
どこでエラーが発生したか
どれだけのトークンとコストが発生したか

AIエージェントがより複雑になり、外部ツール統合が増えるほど、このレベルの可視性は重要になります。信頼性が高く、コスト効率のよいエージェントシステムを構築するには、実行トレースを確認しながら改善するワークフローが不可欠です。

2026年格安LLM APIプロバイダー10選

Akira — Thu, 04 Jun 2026 10:11:57 +0000

単一のAI機能でも、気づかないうちにクラウド費用の最大項目になることがあります。GPT-5.5やClaude Opusを定価で1日に数百万トークン処理すると、リリース前でも月額請求が4桁に達します。モデル自体はどこから呼び出しても同じなので、公式エンドポイントに定価で支払うのは「選択肢の一つ」であり、必須ではありません。

今すぐApidogを試す

2026年に安価なLLM APIを選ぶなら、見るべき対象はプロバイダー公式APIだけではありません。割引ゲートウェイ、プリペイドクレジット型プラットフォーム、オープンモデルホスト、セルフホスティングを比較すると、公式料金より40〜80%低い選択肢が見つかることがあります。ただし、最安値は「モデル」「入力/出力比率」「キャッシュ」「呼び出し頻度」で変わります。

TL;DR: 2026年の最も安価なLLM APIプロバイダー

時間がない場合は、まずこの順に検討してください。

Hypereal AI: Claude、GPT、Geminiなどのプレミアムモデルを安く使いたい場合の有力候補。コーディングプランでは、公式料金より大幅に安くClaudeやGPTを利用できます。
Blackmagic AI: 複数プロバイダーをまたいで、プリペイド残高で利用したい場合に向いています。定価から48〜74%割引をうたうゲートウェイです。
DeepSeek、Google Gemini 3.5 Flash、Groq、DeepInfra: 予算重視の推論、大容量処理、オープンモデル利用で検討すべき選択肢です。
オープンモデルのセルフホスティング: GPU運用ができ、常時高トラフィックがある場合は、トークン課金を避けられるため最安になり得ます。

最短でコストを下げる実装方針はシンプルです。

タスクに必要な最小モデルを選ぶ
公式APIではなく割引プロバイダー経由で呼び出す
usage を測定して実トークン数で比較する
キャッシュ、バッチ、支出上限を設定する

LLM APIのコストが高騰する理由

多くのチームは、安価なモデルで十分な処理に対して、高価なフロンティアモデルを定価で呼び出しています。

LLM APIの料金を見るときは、次の4点を確認してください。

1. 入力トークンと出力トークンは別料金

たとえば「100万トークンあたり $1.32 / $7.92」と書かれている場合、通常は次の意味です。

入力100万トークン: $1.32
出力100万トークン: $7.92

出力トークンは入力より高いことが多いため、長い回答を生成するチャットボットやエージェントは想定以上に高くなります。

2. 定価は上限であり、最安値ではない

OpenAI、Anthropic、Googleなどの公式価格は、小売価格に近いものです。ゲートウェイや再販業者は大量購入によって割引を受け、その一部をユーザーに還元できます。

この価格競争は、フロンティアクラスのモデル価格が下がり続けている2026年の中国LLM価格競争とも関連しています。

3. プリペイドクレジットは管理しやすい

月額サブスクリプションより、プリペイド残高で従量課金する方がコスト管理しやすい場合があります。

ただし、次の点は確認してください。

チャージ時の手数料
最低購入額
失効期限
APIキーごとの上限設定
リアルタイムの利用ログ

4. プロンプトキャッシングは実質的な割引

エージェントやRAGでは、同じシステムプロンプト、ツール定義、コンテキストを何度も送信します。プロンプトキャッシングが使える場合、再利用トークンのコストを大きく下げられます。

5. 無料枠は評価用と考える

無料枠はテストには便利ですが、本番運用にはレート制限が厳しいことが多いです。無料ルートを試す場合は、Gemini 3.5を無料で使う方法とQwen 3.7を無料で使う方法も参考になります。

最も安価なLLM APIのランキング方法

このランキングでは、次の4つを重視します。

実際のトークン単価、または公式価格からの割引率
人気モデルへのアクセス範囲
OpenAI互換APIによる移行しやすさ
プリペイド、支出上限、手数料などの課金予測性

特定の小規模モデルだけ安いプロバイダーより、よく使われるモデル全体で安いプロバイダーを高く評価します。

2026年の最も安価なLLM APIプロバイダー10選

1. Hypereal AI: プレミアムモデルへの最安アクセス

Hypereal AIは、Claude Opus、Claude Sonnet、GPT-5.5、Gemini 3.5のような高価なモデルを安く使いたい場合に検討すべきプロバイダーです。

特にコーディングプランは、コーディングエージェント向けにClaudeやGPTを割引価格で提供します。Claude Opus 4.7は公式API料金より約32%安く、Claude Sonnetは約77%安いとされています。APIはOpenAI互換なので、既存コードでは主に base_url と api_key を差し替える形になります。

料金はクレジットベースです。

100クレジット = $1
利用分だけ支払い
サブスクリプションなし
プロンプトキャッシュとHyperealキャッシュに対応
無料枠では毎分60リクエストでテスト可能

コーディングプランでは、プリペイドパックのサイズに応じて利用乗数が変わります。$10パックでは4.4倍、$1,000パックでは7.7倍になります。

対象モデルには以下が含まれます。

Claude Opus 4.7
Claude Opus 4.6
Claude Sonnet 4.6
GPT-5.5
Gemini 3.5 Thinking / Fast

向いている用途

Claude、GPT、Geminiを使うコーディングエージェント
テキスト、画像、動画を単一の請求で管理したいチーム
Claude Opus 4.8の価格上昇の影響を抑えたいチーム

2. Blackmagic AI: プロバイダー横断のプリペイドゲートウェイ

Blackmagic AIは、OpenRouterスタイルのマルチプロバイダーゲートウェイです。単一のプリペイド残高で複数プロバイダーを利用でき、定価から48〜74%割引をうたっています。

対応プロバイダーには、次のようなものがあります。

OpenAI
Anthropic
Google
Meta
Mistral
xAI
DeepSeek
Qwen
Black Forest Labs
Moonshot AI
Cohere
Perplexity
Stability AI

課金管理機能も実用的です。

サブスクリプションなし
$9.99〜$499.99のチャージ
リクエストごとのリアルタイムコストログ
APIキーごとの月額利用上限

Blackmagic独自の計算では、月間2,000万GPT-5.5トークンを小売価格で使うと約$250かかるのに対し、$66で利用できるとされています。

向いている用途

単一の残高で複数プロバイダーを使いたい
モデルを頻繁に切り替える
APIキー単位で上限をかけたい
料金ログを見ながら運用したい

3. DeepSeek: 低価格なフロンティアクラスモデル

DeepSeekは、フロンティアクラスの推論モデルを低価格で提供する選択肢として知られています。ネイティブAPIは、有能な汎用モデルを安く実行する方法の一つです。

DeepSeekはオープンウェイトモデルでもあるため、選択肢は複数あります。

DeepSeekのネイティブAPIを使う
ゲートウェイ経由で使う
自社インフラでセルフホストする

向いている用途

大容量の推論
コーディング支援
米国大手ラボ以外のフロンティアモデルを許容できるワークロード
オープンモデル価格で高品質を狙うケース

4. Google Gemini 3.5 Flash: 大容量タスク向けの安価なフラッシュティア

Gemini 3.5 Flashは、高スループットでコスト重視のタスクに向いています。

フロンティアモデルほどの推論性能が不要な場合、次のような処理を安く回せます。

要約
分類
情報抽出
ルーティング
軽量なチャット応答
大きなコンテキストを使う前処理

トークンあたりの料金や適したユースケースは、Gemini 3.5 Flashの料金内訳で詳しく確認できます。

向いている用途

数百万件規模の小さな呼び出し
バッチ要約
ルールベース処理の補助
高度な推論よりスループットを優先する処理

5. Groq: 低レイテンシーなオープンモデル推論

Groqは、カスタムLPUハードウェア上でオープンモデルを高速実行します。GroqCloudはOpenAI互換APIを提供し、Llama、Qwen、Gemmaなどをホストしています。

速度と低価格を両立できる点が強みですが、フルアグリゲーターほどモデルカタログは広くありません。モデルが要件に合う場合に有効です。

向いている用途

音声エージェント
リアルタイムチャット
ツール呼び出しの応答速度を重視するアプリ
低レイテンシーがUXに直結する処理

6. DeepInfra: オープンモデルの低価格ホスティング

DeepInfraは、オープンモデルの安価なホスティングに特化しています。トークンごとの従量課金で、OpenAI互換APIを提供します。

対応モデルには、次のような系統があります。

Llama
Qwen
Mistral
DeepSeek

サブスクリプションや最低料金がないため、個人開発から本番利用まで導入しやすい選択肢です。

向いている用途

トークン単価を最優先するオープンモデル推論
小規模プロジェクト
コスト上限のある本番環境
モデル品質より価格効率を重視する処理

7. Together AI: ファインチューニングまで見据えたオープンモデル基盤

Together AIは、OpenAI互換API経由で200以上のオープンモデルを提供します。共有エンドポイントだけでなく、ファインチューニングや専用エンドポイントも利用できます。

安価な共有APIから始めて、必要に応じてチューニング済みモデルや予約済みデプロイメントへ移行できる点が実用的です。

向いている用途

オープンウェイトモデルを標準化したいチーム
まず低コストで試し、後からファインチューニングしたいケース
Qwen系モデルをAPIで使いたいケース

QwenのAPI利用については、Qwen 3.7 APIガイドも参考になります。

8. Fireworks AI: 本番運用向けのオープンモデルAPI

Fireworks AIは、オープンモデル推論を本番環境で運用しやすくする機能に注力しています。

主な特徴は次の通りです。

OpenAI互換API
関数呼び出し
JSONモード
ファインチューニング
高速な推論

単純なトークン単価だけでなく、本番向け機能によって周辺実装の工数を減らせる点がメリットです。

向いている用途

構造化出力が必要なAPI
JSON生成
関数呼び出しを使うアプリ
オープンモデルを本番運用したいチーム

9. OpenRouter: 実験には便利だが手数料に注意

OpenRouterは、単一のキーで300以上のモデルにアクセスできる便利なゲートウェイです。モデル探索や検証には非常に使いやすい選択肢です。

ただし、最安値を狙う場合は手数料を確認する必要があります。

クレジット購入に5.5%手数料
最低$0.80の手数料
月間100万を超える持ち込みキーリクエストに5%手数料
その下にプロバイダー定価が乗る

幅広いモデルを試すには有効ですが、大規模利用で最低コストになるとは限りません。代替案はOpenRouterの最良の代替案で整理しています。

向いている用途

モデルの比較実験
幅広いモデルカタログへのアクセス
本番前のプロトタイピング
最安値より利便性を優先するケース

10. オープンモデルのセルフホスティング: 大規模利用で最安になり得る

GPUインフラを運用できる場合、vLLMのような推論サーバーをLiteLLMなどのプロキシの背後に置き、オープンモデルをセルフホストできます。

この場合、トークン課金ではなくGPU費用を支払います。一定以上の利用量があると、ゲートウェイ経由より安くなる可能性があります。

ただし、次の運用負荷を引き受ける必要があります。

GPU容量計画
スケーリング
稼働監視
モデル更新
障害対応
セキュリティ
レイテンシー最適化

利用量が少ない場合は、自社運用の人件費を含めると、割引ゲートウェイの方が安くなることがあります。

向いている用途

常時GPUが稼働する高トラフィック環境
オープンモデルに標準化しているチーム
推論基盤を自社管理できるチーム

最安価LLM APIプロバイダー比較

プロバイダー	最安値となる対象	料金モデル	例示価格または割引	OpenAI互換
Hypereal AI	プレミアムモデル + メディア	クレジット（100 = $1）	Opus 約32% / Sonnet 約77% 公式料金より割引	はい
Blackmagic AI	プリペイド型マルチプロバイダー	プリペイドクレジット	GPT-5.5 100万トークンあたり$1.32 / $7.92（74%オフ）	はい
DeepSeek	予算重視のフロンティアモデル	従量課金制	フロンティアモデルの中で低料金	はい
Gemini 3.5 Flash	大容量タスク	従量課金制	大手フラッシュティアの中で低料金	はい
Groq	高速 + 安価なオープンモデル	従量課金制	低料金、高速	はい
DeepInfra	オープンモデルホスティング	従量課金制	オープンモデルの低いトークン単価	はい
Together AI	オープンモデル + チューニング	従量課金制	競争力のあるオープンモデル料金	はい
Fireworks AI	本番運用向けオープンモデル	従量課金制	競争力のあるオープンモデル料金	はい
OpenRouter	幅広さ + 利便性	クレジット + 5.5%手数料	定価に手数料を加算	はい
セルフホスト（vLLM）	大規模利用	インフラ費用のみ	大規模利用でトークンあたり低コスト	はい

OpenAI互換APIへ切り替える実装例

多くのプロバイダーはOpenAI互換APIを提供しています。そのため、既存コードでは次の3点を変更するだけで移行できることが多いです。

base_url
api_key
model

Pythonの例です。

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_PROVIDER_API_KEY",
    base_url="https://YOUR_PROVIDER_BASE_URL/v1"
)

response = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[
        {"role": "system", "content": "あなたは簡潔に回答するアシスタントです。"},
        {"role": "user", "content": "この文章を3行で要約してください。"}
    ],
    temperature=0.2
)

print(response.choices[0].message.content)
print(response.usage)

Node.jsの場合です。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PROVIDER_API_KEY,
  baseURL: "https://YOUR_PROVIDER_BASE_URL/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_NAME",
  messages: [
    { role: "system", content: "あなたは簡潔に回答するアシスタントです。" },
    { role: "user", content: "この文章を3行で要約してください。" },
  ],
  temperature: 0.2,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

切り替え時は、次を必ずテストしてください。

ストリーミングレスポンスの形式
usage フィールドの有無
入力/出力トークンのカウント
JSONモード
関数呼び出し
レート制限
エラーコード

LLM APIの費用をさらに削減する5つの方法

安いプロバイダーを選ぶだけでは不十分です。実装側でもコストを下げられます。

1. モデルをタスク別に分ける

すべてのリクエストを最上位モデルに投げる必要はありません。

例:

タスク	推奨ルーティング
分類	Flash / 小型モデル
要約	Flash / オープンモデル
情報抽出	JSON対応の安価なモデル
複雑な推論	フロンティアモデル
コーディング支援	Claude / GPT / Gemini系
低レイテンシー応答	Groqなど

実装例:

function selectModel(taskType) {
  switch (taskType) {
    case "classification":
    case "summary":
    case "extraction":
      return "cheap-flash-model";
    case "coding":
    case "reasoning":
      return "frontier-model";
    default:
      return "default-low-cost-model";
  }
}

まず安価なモデルで処理し、失敗または信頼度が低い場合だけ高価なモデルへフォールバックする構成も有効です。

2. プロンプトキャッシングを使う

エージェントでは、以下のような固定トークンが何度も送られます。

システムプロンプト
ツール定義
リポジトリ情報
RAGの共通コンテキスト

キャッシング対応プロバイダーを使うと、これらの再利用コストを下げられます。Hyperealのようなプラットフォームではキャッシュがデフォルトで有効です。

3. バッチ処理できるものはまとめる

リアルタイム性が不要な処理は、個別リクエストではなくバッチ化します。

向いている処理:

ログ分析
ドキュメント要約
一括分類
ナイトリーバッチ
CSVデータの抽出

4. プリペイドパックは利用量に合わせて選ぶ

割引ティアは購入額が大きいほど有利になることがあります。Hyperealのコーディング乗数は、パックが大きくなるにつれて4.4倍から7.7倍に上がります。

ただし、失効期限や利用予測を確認し、無駄なチャージを避けてください。

5. APIキーごとに支出上限を設定する

暴走ループはLLM API費用の典型的な事故原因です。

最低限、次を設定してください。

APIキーごとの月額上限
プロジェクトごとの上限
アラート通知
レート制限
開発環境と本番環境のキー分離

HyperealとBlackmagicは月額上限やアラートを設定できるため、残高の使い切りを防ぎやすくなります。

Apidogでトークンコストを測定・比較する

料金ページだけを見ても、実際の請求額は分かりません。重要なのは、あなたのプロンプトが実際に消費する入力/出力トークン数です。

Apidogを使うと、OpenAI互換APIのリクエストを同じ条件で比較できます。

実装手順は次の通りです。

各プロバイダーの base_url と api_key をApidogの環境変数に保存する
/chat/completions リクエストを作成する
同じプロンプト、同じパラメータで各プロバイダーに送信する
レスポンスの usage を確認する
入力トークン、出力トークン、レイテンシー、失敗率を比較する

リクエストボディの例です。

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "system",
      "content": "あなたは簡潔に回答するアシスタントです。"
    },
    {
      "role": "user",
      "content": "次の文章を箇条書きで要約してください。"
    }
  ],
  "temperature": 0.2
}

Apidogでは、次のように環境を分けると比較しやすくなります。

環境	base_url	api_key	model
Hypereal	`{{hypereal_base_url}}`	`{{hypereal_api_key}}`	`{{hypereal_model}}`
Blackmagic	`{{blackmagic_base_url}}`	`{{blackmagic_api_key}}`	`{{blackmagic_model}}`
DeepInfra	`{{deepinfra_base_url}}`	`{{deepinfra_api_key}}`	`{{deepinfra_model}}`
Groq	`{{groq_base_url}}`	`{{groq_api_key}}`	`{{groq_model}}`

確認すべきレスポンス例です。

{
  "usage": {
    "prompt_tokens": 850,
    "completion_tokens": 220,
    "total_tokens": 1070
  }
}

比較時は、以下を記録してください。

prompt_tokens
completion_tokens
total_tokens
レスポンス時間
エラー率
出力品質
JSONや関数呼び出しの互換性

ここに挙げたプロバイダーはOpenAI互換APIを提供しているため、同じApidogテストスイートで比較できます。同じプロンプト、同じパラメータ、同じ評価条件で測定することが重要です。

APIテストツールを統合したい場合は、最高のPostman代替品ガイドのワークフローとも相性があります。Apidogをダウンロードすれば、数分で候補プロバイダーの価格比較を始められます。

よくある質問

2026年の最も安価なLLM APIは何ですか？

ClaudeやGPTのようなプレミアムモデルでは、Hypereal AIのコーディングプランが現実的な安価ルートです。オープンモデルでは、DeepInfraとGroqが低いトークン単価を提示しており、DeepSeekは低価格なフロンティアクラス選択肢です。

ただし、真の最安値はワークロードによって変わります。必ず実プロンプトで測定してください。

無料のLLM APIはありますか？

ありますが、基本的には評価用です。Hyperealには毎分60リクエストの無料枠があり、多くの大手ラボもレート制限付きの無料枠を提供しています。

無料ルートを確認する場合は、Claude Opus 4.8を無料で使う方法も参考になります。

なぜ公式APIより安いのですか？

ゲートウェイや再販業者は、大量購入やインフラ効率化によって割引を得て、その一部をユーザーに還元します。オープンモデルホストは、効率的な推論基盤を大規模に運用することで低価格を実現しています。

既存コードはそのまま動きますか？

多くの場合、ほぼ動きます。OpenAI互換APIであれば、変更点は主に以下です。

base_url
api_key
model

ただし、以下は必ず確認してください。

ストリーミング形式
usage フィールド
JSONモード
関数呼び出し
レート制限
エラー処理

Claude CodeやCursorのようなコーディングエージェントに向く安価なAPIは？

Hyperealのコーディングプランが有力です。ClaudeとGPTを小売価格より安く提供し、Claude Code、Cursor、Cline、Aider、Continue.dev、OpenCodeで使えるとされています。

さらに削減したい場合は、エージェントトークンコストガイドの戦術と組み合わせるとよいでしょう。

最も安いモデルを常に選ぶべきですか？

いいえ。トークン単価が安くても、タスクに合わないモデルは再試行や低品質な出力によって総コストが上がります。

選び方は次の順番です。

タスクに合うモデルを選ぶ
そのモデルを最も安く提供するプロバイダーを探す
実プロンプトで usage を測定する
支出上限とログを設定する

どの安価なLLM APIを選ぶべきか

ワークロード別に選ぶと、次のようになります。

Claude、GPT、Geminiをコーディングエージェントで使う

Hypereal AIとコーディングプランを検討します。
複数プロバイダーを単一のプリペイド残高で使いたい

Blackmagic AIを検討します。
オープンモデルを安く使いたい

DeepInfra、Groqを検討します。ファインチューニングや本番機能が必要ならTogether AI、Fireworks AIも候補です。
大容量処理を低予算で回したい

フロンティア品質ならDeepSeek、安価なスループットならGemini 3.5 Flash、GPUを常時使うならセルフホスティングを検討します。

最終判断は、価格表ではなく実測で行ってください。ApidogでOpenAI互換リクエストを作成し、実際のプロンプトを各プロバイダーへ送信し、入力/出力トークン数とレスポンス品質を比較しましょう。