建立端點

端點是 Apidog 中 API 的基本建構單元。本指南介紹如何建立與指定端點，協助你有效定義 API 規格。

什麼是端點？

端點代表一個可透過 HTTP 呼叫的單一 API 操作。每個端點包含：

元件	說明	範例
HTTP 方法	要執行的動作	`GET`, `POST`, `PUT`, `DELETE`
路徑	相對於基礎 URL 的 URL 路徑	`/users/{id}`
參數	路徑、查詢、標頭或主體參數	`id`（路徑參數）
請求主體	隨請求傳送的資料（用於 POST/PUT）	JSON schema
回應	預期的回應格式與狀態碼	`200 OK`, `404 Not Found`

關鍵概念

Apidog 端點以規格為驅動。當你定義端點時，就是同時建立文件與可測試的介面，並會自動產生請求。

前置條件

建立端點之前，請確保你具備：

Apidog account 與 Apidog client application

對 HTTP 方法與 API 概念有基本理解

已在 Apidog 中建立你想新增端點的專案；如需更多資訊，請查看 Overview 頁面。

快速開始：建立基本端點

前往 APIs 模組：點擊側邊欄中的「APIs」分頁

建立新端點：

點擊 New HTTP Endpoint 按鈕，或點擊目錄樹中的 +，然後選擇 New HTTP Endpoint

選擇目標模組／資料夾

此動作會讓你進入 Design-first Mode（或你也可以在發出請求前手動切換），在此模式中你會先定義 API 規格。

端點建立方式

方式	使用時機	步驟
手動建立	從零開始	1. 右鍵點擊資料夾 →「New Endpoint」 2. 填入方法與路徑 3. 定義參數與回應
Import from Code	已有 API 程式碼	1. 使用「Import」功能 2. 上傳 OpenAPI/Swagger 檔案 3. 對應至模組
From Request	測試現有 API	1. 先傳送請求 2. 點擊「Save」 3. 完善規格
複製現有項目	類似的端點	1. 右鍵點擊端點 →「Duplicate」 2. 修改路徑與參數

指定端點詳細資訊

基本資訊

每個端點都需要：

名稱：描述性標題（例如：「取得使用者個人資料」）

方法：HTTP 動詞

路徑：含參數的 URL 路徑

描述：端點的功能

參數

在 Apidog 工作台中，你可以如下定義用於自訂端點行為的參數（值僅作為範例）：

路徑參數

用於 URL 路徑本身：

GET /users/{userId}/posts/{postId}

參數	類型	必填	說明
`userId`	integer	是	唯一使用者識別碼
`postId`	integer	是	貼文識別碼

查詢參數

選用的篩選條件與分頁：

參數	類型	必填	預設值	說明
`limit`	integer	否	10	要回傳的結果數量
`offset`	integer	否	0	要略過的結果數量
`status`	string	否	active	依狀態篩選

請求主體（用於 POST/PUT）

使用 JSON Schema 定義預期的輸入資料：

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "User's full name"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "User's email address"
    }
  },
  "required": ["name", "email"]
}

回應

定義所有可能的回應格式：

成功回應（200 OK）

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2023-01-15T10:30:00Z"
}

錯誤回應

狀態碼	說明	Schema
`400`	Bad Request	錯誤詳細資訊
`401`	Unauthorized	驗證錯誤
`404`	Not Found	找不到資源
`500`	Internal Server Error	伺服器錯誤詳細資訊

Design 分頁包含延伸的 API 規格選項。

下一步

發出請求

建立端點

什麼是端點？#

建立端點#

前置條件#

快速開始：建立基本端點#

端點建立方式#

指定端點詳細資訊#

基本資訊#

參數#

路徑參數#

查詢參數#

請求主體（用於 POST/PUT）#

回應#

成功回應（200 OK）#

錯誤回應#

什麼是端點？

建立端點

前置條件

快速開始：建立基本端點

端點建立方式

指定端點詳細資訊

基本資訊

參數

路徑參數

查詢參數

請求主體（用於 POST/PUT）

回應

成功回應（200 OK）

錯誤回應