設計端點

既然您已經設計好了 schemas 並組織好了專案結構，現在是時候建立實際的端點了。端點是您 API 的入口點——它們定義了客戶端如何與您的資源互動。

在本章中，我們將學習如何在 Apidog 中設計和建立端點，重點關注如何使用 schemas 和範例配置請求和回應。我們將使用我們之前建立的端點計畫並實作 User 模組端點。

1. 什麼是端點？

端點是特定的 URL 路徑結合 HTTP 方法，定義了您 API 中的單一操作。例如：

POST /users — 建立一個新使用者

GET /users/{id} — 獲取一個特定使用者

PUT /users/{id} — 更新一個使用者

DELETE /users/{id} — 刪除一個使用者

每個端點包含：

HTTP 方法 — 要執行什麼動作 (GET, POST, PUT, DELETE)

路徑 — 資源位於何處 (例如 /users/{id})

請求 — 參數、Headers、Body（如果需要）

回應 — API 返回什麼（狀態碼、資料結構、範例）

2. 建立 POST /users 端點（建立使用者）

讓我們從建立 POST /users 端點開始，以建立一個新使用者。此端點示範了如何使用 schemas 和回應配置請求 body。

步驟 1：建立端點

在您的 Apidog 專案中，導航到 APIs 部分 → 您的模組

點擊 「New Endpoint」（或 ➕ → New Endpoint）

設定方法： 選擇 POST

設定路徑： /users

重要： 路徑始終以 / 開頭以符合 OpenAPI 規格

不要包含 base URL（在環境變數中設定）

新增元數據：

名稱："Create User"

描述："在系統中建立一個新使用者帳戶"

標籤："User"

狀態："Developing"（預設）

步驟 2：使用 Schema 配置 Request Body

由於這是一個 POST 請求，我們需要一個 request body：

前往 Request 分頁 → Body

選擇內容類型：JSON

點擊 "Schema" 並從您的 schemas 中選擇 "User"

Apidog 將自動載入 User schema 結構。

步驟 3：自訂建立請求的欄位

User schema 包含所有欄位，但對於建立使用者端點，我們需要調整：

要隱藏的欄位（請求中不需要）：

id — 由系統生成，不提供給客戶端

createdAt — 由系統設定，不提供給客戶端

要新增的欄位（請求中需要但不在基礎 schema 中）：

password — 帳戶建立所需

在 Apidog 中：

隱藏欄位：

懸停在 schema 中的欄位上（例如 id 或 createdAt）

點擊 「Hide」

隱藏的欄位將不會出現在 request body 中

新增欄位：

點擊 「Add Field」 或使用欄位關聯

新增 password 欄位：

類型：string

必需：✅

唯寫 (Write-only)：✅（這對於安全性很重要）

最小長度：8

描述："使用者密碼"

調整必需/可選：

對於建立端點：email, firstName, lastName, password 是必需的

phone 和 preferences 是可選的

根據需要切換每個欄位的 「Required」

步驟 4：生成 Request Body 範例

Apidog 可以根據您的 schema 自動生成 request body 範例：

在 request example 部分點擊 「Add」

在彈出視窗中，點擊 「Auto-generate」

Apidog 將自動建立範例資料，該資料：

符合您的 schema 結構

包含所有可見欄位

使用適當的資料類型和格式

遵循驗證規則（模式、格式等）

生成的範例：

{
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "password": "securePassword123",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  }
}

自訂生成的範例：

直接在 JSON 編輯器中編輯值

修改以顯示不同場景（例如，最小欄位、邊緣情況）

透過點擊 「Add Example」 並再次生成來新增多個範例

自動生成範例的好處：

節省時間 — 無需手動編寫 JSON

始終符合您的 schema — 確保一致性

易於自訂 — 先生成，然後根據需要編輯

步驟 5：配置回應

現在讓我們配置 API 返回什麼：

前往 Response 分頁

點擊 「Add Response」（或 "Add Blank Response"）

選擇狀態碼：201 (Created)

設定內容類型：application/json

點擊 "Schema" 並選擇 "User" schema

將使用 User schema，Apidog 會自動從回應中排除唯寫欄位（如 password）。

步驟 6：生成回應範例

在 response 部分點擊 「Add Example」

點擊 「Auto-generate」

Apidog 將建立範例資料，該資料：

符合您的 schema 結構

使用適當的資料類型

遵循驗證規則（模式、格式等）

尊重欄位約束（唯讀、唯寫）

自動排除唯寫欄位（如 password）

生成的範例：

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

請注意，password 已自動排除（唯寫欄位）。

新增多個回應範例：

再次點擊 「Add Example」

為每個新範例點擊 「Auto-generate」

編輯生成的 JSON 以顯示不同場景（例如，具有最少資料的使用者）

步驟 7：新增錯誤回應

每個端點都應定義錯誤回應：

點擊 「Add Response」

新增常見錯誤回應：

400 Bad Request — 無效輸入

422 Unprocessable Entity — 驗證錯誤

對於錯誤回應，您可以使用共享的 Error Response Component（我們將在下一章介紹）或使用 schema 和範例進行內聯定義。

3. 建立 GET /users/{id} 端點（獲取使用者）

現在讓我們建立 GET /users/{id} 端點以透過 ID 檢索使用者。此端點示範了如何配置路徑參數和回應。

步驟 1：建立端點

點擊 「New Endpoint」

設定方法： 選擇 GET

設定路徑： /users/{id}

{id} 是一個路徑參數（使用大括號 {}，而不是冒號 :）

重要： 路徑始終以 / 開頭

新增元數據：

名稱："Get User"

描述："透過使用者 ID 檢索使用者資訊"

標籤："User"

當您在路徑中寫入 /users/{id} 時，Apidog 自動識別 {id} 為路徑參數。您無需手動新增它。

注意：

在 Apidog 中，路徑中使用 {parameter} 語法，而不是 :parameter

路徑參數會自動偵測——只需在路徑中寫下它們，然後配置其屬性

步驟 2：配置回應

前往 Response 分頁

點擊 「Add Response」

選擇狀態碼：200 (OK)

設定內容類型：application/json

點擊 "Schema" 並選擇 "User" schema

步驟 3：生成回應範例

點擊 「Add Example」

點擊 「Auto-generate」

Apidog 將生成符合 User schema 的回應範例（排除唯寫欄位如 password）。

新增多個範例：

生成額外的範例以顯示不同場景

編輯以顯示有或沒有可選欄位的使用者

步驟 4：新增錯誤回應

新增常見錯誤回應：

404 Not Found — 未找到使用者

400 Bad Request — 無效的使用者 ID 格式

4. 用於請求/回應配置的 Apidog 功能

Apidog 提供了幾個強大的功能來處理請求和回應：

欄位可見性和關聯

在請求中隱藏欄位：

系統生成的欄位 (id, createdAt) 不應出現在建立請求中

懸停在欄位上並點擊 「Hide」 以在請求中隱藏它

隱藏的欄位不會出現在 request body 或範例中

透過關聯新增欄位：

新增僅在特定端點需要的欄位（如建立/登入中的 password）

欄位與端點關聯，而不是基礎 schema

對於特定端點需求很有用

每個端點調整必需/可選：

基礎 schema 定義預設值

每個端點可以覆寫必需/可選設定

對於部分更新（PUT 端點，其中所有欄位都是可選的）很有用

自動範例生成

Apidog 的 Auto-generate 功能自動建立範例：

Request body/Response 範例：

點擊 「Add Example」 → 「Auto-generate」 以從回應 schema 建立範例

自動排除唯寫欄位

建立符合 schema 約束的真實樣本資料

可以生成多個範例並自訂每個範例

好處：

快速 — 在幾秒鐘內生成範例

準確 — 始終符合您的 schema

靈活 — 編輯生成的範例以顯示不同的使用案例

Schema 引用

引用現有 schemas 而不是重複

對 schema 的更改會自動反映在所有端點中

保持整個 API 的一致性

多個範例

為不同場景新增多個範例

為清晰起見命名範例

測試時在範例之間切換

5. 快速參考：其他端點

對於其餘端點，遵循類似的模式：

PUT /users/{id} (更新使用者):

路徑參數：{id} (同 GET)

Request body：User schema，所有欄位可選（部分更新）

隱藏：id, createdAt

不包含：password（使用單獨的端點）

回應：200 帶有 User schema

DELETE /users/{id} (刪除使用者):

路徑參數：{id}

無 request body

回應：204 No Content（無 body）

POST /user/login (登入):

Request body：帶有 username 和 password 的簡單 schema

回應：200 帶有 token 和 expiresAt

POST /user/logout (登出):

無 request body（或可選 body）

回應：200 帶有成功訊息

6. 組織端點

建立端點後，組織它們：

在 Endpoints 下建立資料夾：

User Management/ — POST, GET, PUT, DELETE /users

Authentication/ — Login 和 logout

將端點拖入適當的資料夾

7. 關鍵收穫

設計端點涉及仔細配置請求和回應：

使用 schemas 用於 request 和 response bodies 以保持一致性

每個端點自訂 schemas 使用欄位可見性和關聯

隱藏系統生成的欄位 在請求中 (id, createdAt)

新增端點特定欄位 透過欄位關聯（如 password）

自動生成範例 從 schemas，然後自訂

新增多個範例 以顯示不同場景

定義錯誤回應 以獲得全面的 API 文件

使用 schema 引用 以避免重複並保持一致性

既然您擁有了配置良好的請求和回應的端點，您可以使用可重複使用的元件來增強它們。在下一章中，我們將學習關於 使用元件和可重複使用性 以使您的 API 設計更有效率。

讓我們繼續使用元件和可重複使用性。

1. 什麼是端點？#

2. 建立 POST /users 端點（建立使用者）#

步驟 1：建立端點#

步驟 2：使用 Schema 配置 Request Body#

步驟 3：自訂建立請求的欄位#

步驟 4：生成 Request Body 範例#

步驟 5：配置回應#

步驟 6：生成回應範例#

步驟 7：新增錯誤回應#

3. 建立 GET /users/{id} 端點（獲取使用者）#

步驟 1：建立端點#

步驟 2：配置回應#

步驟 3：生成回應範例#

步驟 4：新增錯誤回應#

4. 用於請求/回應配置的 Apidog 功能#

欄位可見性和關聯#

自動範例生成#

Schema 引用#

多個範例#

5. 快速參考：其他端點#

6. 組織端點#

7. 關鍵收穫#

1. 什麼是端點？

2. 建立 POST /users 端點（建立使用者）

步驟 1：建立端點

步驟 2：使用 Schema 配置 Request Body

步驟 3：自訂建立請求的欄位

步驟 4：生成 Request Body 範例

步驟 5：配置回應

步驟 6：生成回應範例

步驟 7：新增錯誤回應

3. 建立 GET /users/{id} 端點（獲取使用者）

步驟 1：建立端點

步驟 2：配置回應

步驟 3：生成回應範例

步驟 4：新增錯誤回應

4. 用於請求/回應配置的 Apidog 功能

欄位可見性和關聯

自動範例生成

Schema 引用

多個範例

5. 快速參考：其他端點

6. 組織端點

7. 關鍵收穫