自訂模擬

Apidog 提供強大的模擬自訂功能，讓你能精細控制 API 回應。本文件介紹兩種自訂模擬資料的方法：

欄位層級自訂：控制特定欄位，同時讓其他欄位使用智慧模擬

完整回應自訂：使用期望定義完整的模擬回應（固定、條件式或動態）

欄位層級自訂

有時你需要為某些欄位定義特定值，同時讓 Apidog 自動產生其餘內容。Apidog 提供彈性的方法來進行欄位層級控制。

設定自訂欄位值

1. 固定值

在端點規格的模擬欄位中指定靜態值。Apidog 會一律為該欄位回傳這個確切值，而未指定的欄位則使用智慧模擬。

範例：

2. 使用 Faker.js 的動態值

使用 Apidog 的動態值（基於 Faker.js）產生逼真的隨機資料。使用語法：

{{$category.method}}

常見範例：

表達式	範例結果
`{{$person.fullName}}`	Rachel Wheeler
`{{$internet.email}}`	Arno.Huels33@yahoo.com
`{{$commerce.productName}}`	Elegant Plastic Bike

直接從下拉式選單選取動態值：

3. 帶參數的 Faker 方法

使用 Apidog 增強版 Faker.js 語法，將參數傳入動態值方法，以產生專用資料。

範例：

使用情境	表達式	說明
整數範圍	`{{$number.int(min=0,max=10000)}}`	0 到 10,000 之間的隨機整數
易讀電話	`{{$phone.number(style='human')}}`	人類可讀的電話格式
N 的倍數	`{{$number.int(multipleOf=3)}}`	可被 3 整除的整數
陣列元素	`{{$helpers.arrayElement(['red','blue','green'])}}`	從陣列中隨機選取顏色
日期範圍	`{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}`	指定範圍內的日期

在 Dynamic Values Modules documentation 中探索完整的模組、方法與參數清單。

4. 串接多個表達式

結合靜態文字與多個動態表達式，以產生複雜欄位值。

範例：完整地址產生

{{$location.streetAddress}}, {{$location.city}}, {{$location.state}}, {{$location.zipCode}}, {{$location.country}}

範例輸出：

8507 Hudson Alley, Rochester, Wisconsin, 96512, United States

每個組成部分都會動態產生，為每次模擬 API 呼叫建立獨特且逼真的地址。

模擬語系

Apidog 支援可自訂的模擬語系，讓你能以符合目標地區或受眾的不同語言與格式產生動態測試資料。若要了解更多關於設定模擬語系的資訊，請造訪 Mock language (Locales)。

完整回應自訂（模擬期望）

若要完全控制模擬回應，請使用 模擬期望。此功能可讓你定義固定、條件式或動態回應。

建立模擬期望

固定回應

透過建立無條件期望，讓每個請求都回傳相同資料。

步驟：

點選 New expectation

新增期望名稱並將條件留空

填入你想回傳的回應資料，然後儲存

複製並使用提供的模擬 URL 來存取此端點

條件式回應

根據請求參數回傳不同的模擬資料。模擬引擎會由上到下評估條件，並回傳第一個符合的期望。

支援的條件類型：

參數類型	說明
查詢參數	URL 查詢字串
路徑參數	動態 URL 區段
標頭參數	HTTP 標頭
Cookie 參數	Cookie 值
主體參數	JSON 主體欄位（透過 JSON path）

條件行為

多個條件會以 AND 邏輯組合（全部都必須符合）

如果沒有任何條件符合，Apidog 會回退到 Project Settings → Feature Settings → Mock Settings 中的模擬方法優先順序

限制

主體參數僅支援 JSON，不支援 XML

參數條件無法使用 {{variables}}

請求主體格式必須符合 API 規格（例如 form-data、JSON）

IP 位址條件可將回應限制為特定 IP

動態模擬資料

模擬期望支援使用 Faker.js 與 Nunjucks 範本語法產生動態、隨機化資料。

範例：

{
    "data": [
        {% for i in range(0, 20) %}
        {% if i>1 %},{% endif %}
        {
            "id": {{i}},
            "firstname": "{{$person.firstName}}",
            "lastname": "{{$person.lastName}}"
        }
        {% endfor %}
    ],
    "success": true
}

這會產生：

包含 20 個使用者物件的陣列（id 從 0 到 19）

每個物件都有隨機產生的名字與姓氏

一個固定的 "success": true 欄位

語法說明：

語法	用途
`{{$...}}`	呼叫 Faker.js 以產生隨機值
`{% for ... %}`	Nunjucks 迴圈結構
`{{i}}`	Nunjucks 迴圈變數（不是 Apidog 變數）

重要差異

Apidog 使用 {{$person.firstName}}，而不是原生 Faker.js 的 faker.person.firstName()

Apidog 專案／環境變數（{{variable}}）在模擬期望中無法使用

請參閱 Faker.js 與 Nunjucks 文件以了解完整語法

進階功能

自訂回應標頭

將自訂標頭新增到模擬期望，以模擬驗證、分頁或其他 API 行為。

進階回應屬性

在 More 分頁中設定其他回應屬性：

屬性	用途	預設值
HTTP Status Code	模擬錯誤或特殊情況	200
Response Delay	模擬網路延遲（毫秒）	0

啟用／停用期望

可從期望清單中，分別為本機與雲端模擬環境切換期望的啟用或停用狀態。

摘要

Apidog 的自訂模擬功能提供：

使用固定值或動態值的彈性欄位自訂

透過模擬期望進行完整回應控制

用於參數式回應的條件邏輯

使用 Faker.js 與 Nunjucks 的動態資料產生

透過自訂標頭、延遲與狀態碼進行進階模擬

這些功能可讓你建立穩健且高擬真度的 API 模擬，準確反映正式環境行為！

欄位層級自訂#

設定自訂欄位值#

1. 固定值#

2. 使用 Faker.js 的動態值#

3. 帶參數的 Faker 方法#

4. 串接多個表達式#

完整回應自訂（模擬期望）#

建立模擬期望#

固定回應#

條件式回應#

動態模擬資料#

進階功能#

自訂回應標頭#

進階回應屬性#

啟用／停用期望#

摘要#

欄位層級自訂

設定自訂欄位值

1. 固定值

2. 使用 Faker.js 的動態值

3. 帶參數的 Faker 方法

4. 串接多個表達式

完整回應自訂（模擬期望）

建立模擬期望

固定回應

條件式回應

動態模擬資料

進階功能

自訂回應標頭

進階回應屬性

啟用／停用期望

摘要