アピドッグで条件分岐モックデータを返す方法 (カスタムルールとモックスクリプト)

Smart mock（スマートモック）を使えば、数秒でフェイクAPIを作成できます。エンドポイントのスキーマを読み取り、本物らしいメールアドレス、意味のあるタイムスタンプ、ランダム文字列ではない名前などを返します。多くのフロントエンド開発では、これだけでバックエンド待ちを解消できます。

今すぐApidogを試す

ただし、リクエスト内容によってレスポンスを分岐したいケースでは、Smart mockだけでは足りません。たとえば、/loginで既知のユーザーには200、それ以外には401を返すケースや、/orders/{id}で注文IDごとに発送済み・キャンセル済みを返し分けるケースです。特定のヘッダーを指定したときだけ500を返し、エラーハンドリングを検証したい場合もあるでしょう。

Smart mockはエンドポイントごとに1つのレスポンス形状を生成します。リクエストに応じた分岐には、Apidogのモック期待値またはモックスクリプトを使用します。この記事では、条件付きレスポンスを実装する手順、期待値の優先順位、スクリプトを使うべき場面を具体例とともに解説します。

基礎から確認したい場合は、APIモックの概要も参照してください。Apidogはこの記事で使用するツールです。OpenAPI Initiativeでは、このような契約ファーストのワークフローが文書化されています。

条件付きモックとは

条件付きモックは、次のようなルールです。

リクエストがこの条件に一致したら、このレスポンスを返す

Apidogでは、モックを大きく2つのレイヤーで構成できます。

1. フィールドレベルの動的値
2. フルレスポンスのモック期待値

フィールドレベルの動的値

スキーマ内のフィールドに固定値やFaker.js式を設定できます。これは「各フィールドに何を入れるか」を制御する仕組みです。

ただし、返却するレスポンス形状は1つです。リクエストに応じた200/401の切り替えや、パスパラメータ別のレスポンス分岐はできません。

モック期待値

モック期待値は、以下を持つ名前付きルールです。

• 任意の一致条件
• レスポンスボディ
• HTTPステータスコード
• レスポンスヘッダー
• レスポンス遅延

条件なしの期待値は、常に固定レスポンスを返します。条件ありの期待値は、リクエストが一致したときだけ返されます。

複数の期待値を並べることで、以下のような分岐を実装できます。

• リクエストボディの値に応じて200または401
• パスパラメータごとに異なる注文ステータス
• 特定ヘッダーを指定した場合のみ500
• ヘッダー未指定時にエラーレスポンス
• クエリ、Cookie、IPアドレスに応じたレスポンス

以降では、このモック期待値を中心に扱います。

まずはフィールドレベルの動的値を設定する

条件分岐の前に、Smart mockで使う動的な値を確認しておきましょう。Faker.js式は、期待値のレスポンスデータ内でも利用できます。

エンドポイントスキーマの文字列フィールドには、{{$category.method}}形式のFaker.js式を指定できます。

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

パラメータ付きメソッドを使うと、生成範囲も制御できます。

• {{$number.int(min=1000,max=9999)}}: 数値の最小・最大値を指定
• {{$date.between(...)}}: 日付範囲とフォーマットを指定
• 複数の式と静的テキストを1フィールドに連結: 住所などの生成に利用

Apidogは、JSON Schemaですでに定義されているフィールド型に従って、モック呼び出しごとに値を生成します。地域に合った氏名、住所、電話番号が必要な場合は、モックロケールも設定できます。

利用可能な式は、ApidogのFaker.jsリファレンスで確認できます。

これはSmart mockの役割です。値は動的ですが、リクエスト条件による分岐はしません。分岐するにはモック期待値を使います。

ウォークスルー: POST /loginで200または401を返す

ここでは、次の仕様をモックします。

• POST /login
• JSONボディにusernameとpasswordを受け取る
• [e-mail]ならトークン付きの200
• それ以外なら401

1. モック期待値の画面を開く

設定場所は作業モードによって異なります。

• DEBUG（Request-first）モード: エンドポイントを開き、Mockタブを選択

• DESIGN（Design-first）モード: エンドポイントを開き、Advanced mockタブを選択

どちらも同じ期待値リストを開きます。まだエンドポイントがない場合は、Apidogをダウンロードして、まず/loginを作成またはインポートしてください。

2. 成功用の期待値を追加する

New expectationをクリックし、次のように設定します。

項目	設定値
期待値名	login-success
条件の対象	ボディパラメータ
名前	username
条件	[e-mail]と等しい
HTTPステータスコード	200

JSONボディの条件は、名前フィールドでJSONパスを指定して一致させます。ネストした値を参照する場合は、user.emailのようなドットパスを使います。

Response dataには、成功時のレスポンスを設定します。

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

保存します。HTTPステータスコードのデフォルトは200です。

3. 失敗用の期待値を追加する

もう一度New expectationをクリックし、次のように設定します。

項目	設定値
期待値名	login-failure
条件	なし
HTTPステータスコード	401

条件を空にすることで、この期待値はキャッチオールになります。

Response dataには、認証失敗のレスポンスを設定します。

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

次に、期待値のMoreタブを開き、HTTPステータスコードを401に変更します。

このタブでは、以下も設定できます。

• レスポンス遅延（ミリ秒）
• カスタムレスポンスヘッダー

たとえば、400ミリ秒の遅延を設定すると、ローディングスピナーが実際に表示されるかを確認できます。

4. 期待値の順序を確認する

期待値は上から下へ評価され、最初に一致したものが返されます。

したがって、並び順は必ず以下にします。

1. login-success
2. login-failure

login-failureを上に置くと、条件なしのルールがすべてのリクエストに一致します。その結果、成功用の期待値は実行されません。

エンドポイントのモックURLをコピーして、2パターンを確認します。

# 既知のユーザー -> トークン付きで200
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# その他のユーザー -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

ウォークスルー: /orders/{id}を注文状態ごとに返し分ける

次は、パスパラメータでレスポンスを分岐します。

• /orders/5001は発送済み
• /orders/5002はキャンセル済み
• それ以外は保留中

この構成にすると、ライブバックエンドがなくても、フロントエンドで全ステータスのUIを確認できます。

1. 発送済み注文の期待値を作成する

期待値名をorder-shippedに設定します。

条件は以下です。

項目	設定値
条件の対象	パスパラメータ
パラメータ名	id
条件	5001と等しい

Response data:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

2. キャンセル済み注文の期待値を作成する

期待値名をorder-cancelledに設定します。

条件は、パスパラメータidが5002と等しいことです。

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

3. 条件なしのフォールバックを追加する

最後に、条件なしで保留中の注文を返す期待値を追加します。

このキャッチオールを用意しておくと、5001と5002以外のIDでも有効なレスポンスを返せます。

期待値は次の順番に並べます。

1. order-shipped
2. order-cancelled
3. 条件なしの保留中注文

複数条件を追加した場合、ApidogはAND条件として評価します。たとえば、パスパラメータid=5001に加え、特定ヘッダーを指定した場合、両方を満たしたリクエストだけが一致します。

条件の対象はボディやパスだけではありません。

• クエリパラメータ
• ヘッダーパラメータ
• Cookieパラメータ
• IPアドレス

これらを使うと、特定のクライアントやテストシナリオだけに異なるレスポンスを返せます。

オンデマンドでエラー状態を強制する

壊れたレスポンスのテストに、壊れたバックエンドは不要です。モック期待値の条件とMoreタブを使えば、任意のエラー状態を再現できます。

たとえば、500を返す期待値を作成します。

項目	設定値
条件の対象	ヘッダーパラメータ
ヘッダー名	X-Mock-Scenario
条件	server-errorと等しい
HTTPステータスコード	500

Response data:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

これで通常は200を返しつつ、次のようなリクエストだけ500を返せます。

curl https://<your-mock-host>/orders/5001 \
  -H "X-Mock-Scenario: server-error"

同じ方法で、以下もテストできます。

• 404 Not Found
• 429 Too Many Requests
• 503 Service Unavailable

429の場合は、MoreタブでRetry-Afterヘッダーも設定できます。

共有プロジェクトでは、期待値ごとにローカル環境とクラウド環境で個別に有効・無効を切り替えられます。たとえば、ローカルでは500ルールを有効にし、チームが使うクラウドモックでは無効にする、といった運用が可能です。

自動テストでこれらのレスポンスを検証する場合は、APIアサーションのガイドも役立ちます。

ルールで表現できない場合はモックスクリプトを使う

モック期待値は宣言的なルールです。条件に一致したら固定のレスポンスを返せますが、複雑な計算には向きません。

以下のようなケースでは、モックスクリプトを使用します。

• リクエストの明細から合計金額を計算する
• ヘッダー値で通貨を切り替える
• 複数入力からレスポンスの形状を組み立てる
• 日付や配列を使った計算を行う

モックスクリプトは、モックレスポンス生成時に実行されるJavaScriptです。Mockタブ下部のMock Scriptセクションでトグルを有効にします。

スクリプトでは主に次のグローバルオブジェクトを使います。

• $$.mockRequest: 着信リクエストを参照
• $$.mockResponse: 返却レスポンスを変更

$$.mockRequestでは、以下を利用できます。

• getParam(key)
• headers
• cookies
• body
• formdata
• urlencoded

$$.mockResponseでは、以下を利用できます。

• setBody()
• setCode()
• setDelay()
• json()
• headers
• code

たとえば、注文明細から金額を計算するスクリプトは次のようになります。

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

処理の流れは以下です。

1. Smart mockが初期レスポンスを生成する
2. スクリプトが$$.mockRequestと$$.mockResponseを読み取る
3. JavaScriptロジックを実行する
4. setBody()、setCode()、setDelay()などでレスポンスを更新する
5. 更新後のレスポンスが返される

配列操作や日付計算を追加したい場合は、MDN JavaScriptリファレンスを参照してください。

モックスクリプトの重要な制約

モックスクリプトはSmart mockでのみ動作します。

モック期待値やレスポンス例には適用されません。期待値がリクエストに一致した場合、モックスクリプトは実行されません。

つまり、エンドポイントごとに基本的には次のどちらかを選びます。

要件	選択する機能
固定条件で分岐し、定義済みボディを返す	モック期待値
リクエストから計算した値を返す	モックスクリプト

モックの優先順位

Apidogは、モックリクエストを次の順序で処理します。

1. 期待値を上から下へ評価する

   • 最初にすべての条件に一致した期待値のレスポンスを返す
   • 一致した期待値があれば、Smart mockは使われない

2. 一致する期待値がない場合、モックメソッドの優先順位にフォールバックする

   • プロジェクト設定 → 機能設定 → モック設定で設定
   • Smart mockと、それに接続されたモックスクリプトがこの階層で使われる

実装時は、以下の順序を守ると安全です。

1. 最も具体的な期待値
2. 条件が少ない期待値
3. 条件なしのキャッチオール
4. Smart mockへのフォールバック

基本の考え方はシンプルです。

まず具体的なルール、次に生成データ

各レイヤーの使い分けは、APIモックのユースケースガイドでも確認できます。

実装前に確認したい注意点

モック期待値とモックスクリプトには、いくつかの制約があります。

• パラメータ条件では{{variables}}を使用できません。Apidogのプロジェクト変数や環境変数は、モック期待値内では使えないため、条件にはリテラル値を指定してください。
• ボディパラメータの条件はJSONのみ対応です。XMLでは使用できません。
• JSONボディの条件は、名前フィールドのJSONパスを使って指定します。
• リクエストボディの形式はAPI仕様と一致させる必要があります。フォームデータのエンドポイントは、JSONではなくフォームデータとして設定してください。
• モックスクリプトにはログ関数がありません。
• モックスクリプトではpmオブジェクトを利用できません。テストスクリプトとは実行環境が異なります。
• モックスクリプト内ではApidog変数を使用できません。ロジックは自己完結型にしてください。

これらの機能について、ドキュメント上ではプランによる制限は示されていません。ローカルとクラウドの違いは、期待値を環境ごとに個別オン・オフできる点です。

Apidog CLIでワークフローを自動化する

ApidogのモックはGUIとクラウド機能で提供されます。ローカルおよびクラウドのモックURLからエンドポイントを提供しますが、CLIでモックサーバーを起動するコマンドはありません。

Apidog CLIが扱うのは、モックの基盤となるAPI仕様、エンドポイント、スキーマです。

モックレスポンスはエンドポイントスキーマから生成されるため、仕様を更新すればモック出力も追随します。CLIや、それを利用するAIコーディングエージェント（Cursor、Claude Code、Trae、Codex）を使うと、プロジェクト内のエンドポイントやスキーマを作成・更新できます。

フロントエンド開発をモックで進めた後は、同じプロジェクトのテストシナリオをCIでヘッドレス実行し、実際のバックエンドが契約どおりか検証できます。

apidog run -t <scenario_id> -e <env_id> -r cli

このコマンドはテストシナリオを実行し、結果を報告します。モックと検証が同じAPI仕様を共有できる点が重要です。

セットアップはApidog CLIインストールガイド、CIへの組み込みはGitHub ActionsでのApidog CLIウォークスルーを参照してください。

よくある質問

条件が正しく見えるのに、期待値が無視されるのはなぜですか？

多くの場合、期待値の順序またはリクエスト形式が原因です。

期待値は上から下へ評価されます。条件なしの広いルールが特定ルールより上にあると、先にそのリクエストを処理してしまいます。

また、ボディ形式も確認してください。

• JSONボディ: JSONパスを使用
• フォームエンドポイント: フォームデータとして条件を設定

基本設定はAPIモックの概要で確認できます。

モックスクリプトとモック期待値を同じレスポンスで使えますか？

いいえ。モックスクリプトはSmart mockでのみ実行されます。

期待値が一致した場合、モックスクリプトは実行されません。ルールベースの分岐には期待値、計算した出力にはスクリプトを使ってください。

デフォルトの200を壊さずに401や500を返すには？

クライアント側から制御できる条件を持つ専用の期待値を追加します。ヘッダー条件が扱いやすい選択肢です。

たとえば、X-Mock-Scenario: server-errorのときだけ500を返す期待値を作成します。通常のリクエストは既存どおり200を返します。

条件で環境変数を使えますか？

いいえ。モック期待値内ではApidogの{{variable}}値を使用できません。条件にはリテラル値を指定してください。

どの期待値も一致しない場合はどうなりますか？

Apidogは、プロジェクト設定 → 機能設定 → モック設定のモックメソッド優先順位にフォールバックします。Smart mockはスキーマをもとにレスポンスを生成します。

必ず特定のフォールバックを返したい場合は、条件なしのキャッチオール期待値を追加してください。

まとめ

Smart mockは、スキーマからもっともらしいデータを生成するための機能です。モック期待値は、もし〜ならばという条件分岐を実装するための機能です。

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

• 既知ユーザーに200、その他に401: モック期待値
• 注文IDごとに異なる注文状態: モック期待値
• ヘッダー指定時だけ500: モック期待値
• リクエスト明細から金額を計算: モックスクリプト

期待値は「具体的なものから一般的なもの」の順に並べます。一致する期待値がなければSmart mockへフォールバックします。この優先順位を理解しておけば、実APIに近い分岐を持つモックを構築できます。

Apidogをダウンロードして、最初の条件付きモックを構築してみましょう。クレジットカードは不要です。