設定與 Auth

大多數 API 都需要某種形式的保護。您不希望任何人都能刪除使用者帳戶或存取私人資料。這就是 身分驗證 (Authentication) 和 授權 (Authorization) 發揮作用的地方。

在本章中，我們將學習如何為我們的 API 設定身分驗證。我們將在 Apidog 中定義安全方案 (Security Schemes) 並將其應用於我們的 User 模組端點。

1. 了解 API 身分驗證

在 API 中，有幾種常見的身分驗證方法：

API Key: 一個簡單的字串，通常在 Header 或 Query 參數中發送。適用於系統對系統的整合。

Bearer Token (JWT): 最常見於現代 Web/Mobile 應用。使用者登入換取一個 Token，然後在每個請求的 Header 中發送該 Token (Authorization: Bearer <token>)。

Basic Auth: 使用者名稱和密碼經過 Base64 編碼。較舊，不再推薦用於公共 API。

OAuth 2.0: 用於授權的行業標準，允許第三方應用代表使用者存取資源。

對於我們的 Pet Store User 模組，我們將使用 Bearer Token (JWT)。這是最適合使用者帳戶系統的選擇。

2. 在 Apidog 中定義安全方案 (Security Component)

在 OpenAPI/Apidog 中，您不是在每個端點手動新增 Header，而是定義一個 "Security Scheme" (安全方案) 元件，然後引用它。

步驟 1：建立安全方案

在您的 Apidog 專案中，前往 Components。

選擇 Security Schemes。

點擊 ➕ New Security Scheme。

配置 JWT 方案：

Name: UserAuth (或 BearerAuth)

Type: http

Scheme: bearer

Bearer Format: JWT (可選，但在文件中很有用)

Description: "Standard JWT Authorization. Send the token in the header as: Authorization: Bearer <token>"

步驟 2：了解它做什麼

這定義了 API 支援這種身分驗證方法。它告訴 Apidog (以及生成的文檔)：
"此 API 使用 HTTP Bearer 驗證。客戶端應該在 Authorization header 中發送一個 token。"

3. 將身分驗證應用於端點

定義方案後，您需要將其應用於需要保護的端點。

全局應用 vs 每個端點應用

全局 (Global): 如果所有或大多數端點都需要身分驗證。

每個端點 (Per-Endpoint): 如果只有特定端點需要。

對於我們的 User 模組：

公開 (Public) 端點:

POST /users (註冊)

POST /user/login (登入)

受保護 (Protected) 端點:

GET /users/{id} (讀取個人資料)

PUT /users/{id} (更新個人資料)

DELETE /users/{id} (刪除帳戶)

POST /user/logout (登出)

由於我們有混合的情況，我們可以在端點層級控制，或者設定全局預設並在公開端點覆蓋。為了示範，我們將在端點層級應用。

步驟 3：保護 `GET /users/{id}`

前往 GET /users/{id} 端點編輯器。

向下捲動到 Security 部分 (通常在 Request 設定附近)。

您會看到我們定義的 UserAuth 方案。

切換開關以啟用它。

現在，GET /users/{id} 被標記為需要 UserAuth。如果有人嘗試測試此端點，Apidog 會提示輸入 token。

步驟 4：為其他受保護端點重複步驟

對 PUT /users/{id}, DELETE /users/{id}, 和 POST /user/logout 重複上述步驟。

確保 POST /users 和 POST /user/login 保持停用狀態。這些是公開入口點，不需要 token。

雖然 UserAuth 方案處理如何發送 token，但我們還需要一個端點來獲取 token。這就是 POST /user/login。

步驟 1：設計 Request

前往 POST /user/login。

很簡單，只需要一個包含憑證的 request body。

建立一個名為 "LoginCredentials" 的新 schema (或直接在端點定義)：

{
  "email": "jane@example.com",
  "password": "secretpassword"
}

將此 schema 用於 request body。

步驟 2：設計 Response

成功登入應返回 token。

在 Response (200 OK) 中，定義返回結構。

建立一個名為 "AuthToken" 的 schema：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5...", 
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

token (string): 實際的 JWT 字串。

expiresIn (integer): 有效期秒數 (可選)。

tokenType (string): 通常是 "Bearer"。

5. 測試身分驗證流程

在開發階段，您會想要測試此流程。

使用 Apidog 進行測試

呼叫 Login:

執行 POST /user/login。

複製回應中的 token 值。

呼叫受保護端點:

執行 GET /users/{id}。

點擊 Request 面板中的 "Auth" 或 "Security" 分頁。

選擇 UserAuth。

貼上 Token。

發送請求。

提示： Apidog 有動態變數和環境變數功能。您可以設定 Login 端點的 Post-request script 自動將 token 保存到環境變數（例如 {{ACCESS_TOKEN}}），然後在 UserAuth 配置中引用該變數。這樣您登入一次，所有受保護端點都會自動使用新 token，無需手動複製貼上。

6. 其他安全最佳實踐

始終使用 HTTPS: 這是必須的。如果沒有 SSL/TLS，Token 和密碼會以純文字傳輸。

最小權限: Token 應只授予必要的權限 (Scopes)。

Token 過期: Token 應該有較短的壽命。使用 Refresh Token 獲取新的 Access Token。

錯誤訊息: 登入失敗時，返回泛用的 "Invalid email or password"，不要透露是哪個錯誤（防止枚舉攻擊）。

7. 關鍵收穫

安全方案 (Security Schemes): 是可重複使用的元件，定義 API 支援的驗證類型 (Bearer, API Key, OAuth)。

應用範圍: 可以全局應用於所有端點，或針對特定端點應用。

Login 端點: 是獲取 token 的機制，通常返回 JWT。

混合模式: 大多數 API 都有公開端點 (Login, Register) 和受保護端點。

整合測試: 確保包括從 Login 獲取 Token 並用於後續請求的流程。

現在我們的 API 結構良好、資料模型清晰、端點已定義且安全性已配置。在開始編寫程式碼之前，我們需要確保我們的設計符合行業標準。在下一章中，我們將回顧 API 設計指南。

讓我們繼續 API 設計指南。

1. 了解 API 身分驗證#

2. 在 Apidog 中定義安全方案 (Security Component)#

步驟 1：建立安全方案#

步驟 2：了解它做什麼#

3. 將身分驗證應用於端點#

全局應用 vs 每個端點應用#

步驟 3：保護 GET /users/{id}#

步驟 4：為其他受保護端點重複步驟#

4. 設計 Login 端點#

步驟 1：設計 Request#

步驟 2：設計 Response#

5. 測試身分驗證流程#

使用 Apidog 進行測試#

6. 其他安全最佳實踐#

7. 關鍵收穫#