端點基礎

在 Apidog 中，設計與設定 API 端點是建立穩健且有效 API 的基礎步驟。

建議依循 OpenAPI Specification (OAS) 設計端點，以確保與 OpenAPI 生態系中各種工具與服務順利相容。若偏離 OAS，在使用符合 OpenAPI 規範的工具與服務時，可能會導致相容性問題。

建立端點

若要在 APIs 模組中建立新的端點，請按一下 New Endpoint 按鈕。

清楚且完整的端點應包含以下元素：

端點路徑

請求方法

端點中繼資料

請求

回應與範例

設計優先模式

請求優先模式

介面模式

Apidog 的端點介面有兩種模式：用於 API Design-first 的 設計優先模式，以及用於 Code-first 方法的 請求優先模式。你可以在介面的左下角切換模式。深入了解設計優先模式/請求優先模式。

端點路徑

端點路徑是 API 可與外部應用程式互動的特定位址。這是用戶端用來存取 API 服務的內容。

Apidog 遵循 OpenAPI Specification 的方式。你不需要為每個端點撰寫完整 URL，只需要輸入路徑（例如 /users）。基礎 URL 會在環境中設定，Apidog 會在向端點發出請求時自動加入它。

為了與 OpenAPI 標準保持一致，Apidog 也建議所有路徑都以 / 開頭。這能讓你的 API 設計保持清晰、有條理，並確保你能完整運用 Apidog 的功能。

為什麼路徑要以 / 開頭

建議路徑以 / 開頭，以符合 OAS。若路徑未以 / 開頭，在使用 OpenAPI 生態系中的工具時，可能會導致各種相容性問題。

此外，在路徑開頭使用 / 可啟用 URL pattern mock 功能，這對 Apidog 中的測試與驗證目的至關重要。

請求方法

請求方法決定用戶端如何與伺服器端資源互動。每種方法都有自己的語意，並決定伺服器的回應。設計 API 時，請根據業務需求選擇最合適的請求方法，以有效執行預期操作。

以下是常用的 API 請求方法：

方法	說明
GET	擷取指定資源，且不產生副作用。使用查詢參數傳輸資料。
POST	提交資料以進行處理，且可能產生副作用。資料通常會在請求主體中傳送。
PUT	完整更新或取代指定資源。
DELETE	移除指定資源。
OPTIONS	查詢目標資源支援的 HTTP 方法。
HEAD	類似 GET，但只擷取回應標頭。適用於不下載資源內容的情況下檢查資源是否存在與是否被修改。
PATCH	更新指定資源的部分資訊。
TRACE	返回伺服器接收到的請求。主要用於偵錯與診斷目的。
CONNECT	建立到伺服器的通道，通常用於代理伺服器的請求轉送。

端點中繼資料

在 Apidog 中，端點附有預設中繼資料欄位，用於定義與管理 API 的文件、可存取性與生命週期。

以下是每個預設中繼資料欄位的簡要概述：

欄位	說明
Name	描述端點功能的說明性名稱。
Status	預設狀態為「Developing」。你可以修改此狀態以反映不同階段，例如 Testing 或 Production。深入了解端點狀態。
Maintainer	指定負責此端點的 Apidog 團隊成員。從你的帳戶中選取使用者以指派此角色。
Tags	用於分類或描述端點的關鍵字或片語。你可以建立新標籤，或從現有標籤中選取。
Service	端點路徑會附加到的基礎 URL。預設設定為「Inherit from parents」，但可透過環境設定手動指定。深入了解環境與服務。
OperationId	用於在 API 中區分此操作的唯一識別碼（OAS 中的 operationId）。
Description	關於端點用途與使用方式的詳細資訊，支援 Markdown 以增強格式呈現。

自訂欄位

除了端點提供的標準中繼資料欄位外，你也可以彈性地新增自訂欄位，以進一步豐富端點的中繼資料。

請求

請求參數

請求參數是可隨請求一起傳遞的選項，用於控制資料回傳或修改伺服器的回應。

請求參數包含查詢參數、路徑參數、標頭參數和主體參數。

查詢參數

查詢參數是附加在 URL 結尾問號 ? 之後的鍵值對，並以 & 分隔，如下所示：?id=2&status=available。它們用於篩選、排序或修改 API 端點的輸出。

INFO

在 Apidog 中，為了清楚與有條理，查詢參數會在獨立區段中描述。不過，在傳送請求時，這些查詢參數會以上述方式與端點路徑串接。

路徑參數

路徑參數是端點 URL 本身的一部分，用於識別 API 中的特定資源或實體。

在 Apidog 中，路徑參數使用大括號表示，而不是冒號。正確範例：/pets/{id}，錯誤範例：/pets/:id。

如果你需要在路徑參數中使用變數，建議的方法是在 URL 中將其定義為 {parameter}，然後使用 {{variable}} 作為參數值。例如：

建議：將變數放在路徑參數值中

不建議：將變數直接放在 URL 中

不要混淆 {parameter} 與 {{variable}}

{parameter}：單層大括號代表 Apidog 中的路徑參數。路徑參數是 URL 路徑中的預留位置，當存取 API 端點時，會動態變更為特定值。

{{variable}}：雙層大括號用於在請求中包含變數。傳送請求時，這些變數可被實際值取代，讓 API 互動中的輸入具備動態與可自訂能力。

為什麼不要在路徑中使用 {{variable}}

使用 {{variable}} 不符合 OAS。遵循 OAS 可與 OpenAPI 生態系中的各種工具無縫整合。

在路徑中使用 {{variable}} 將無法使用 Apidog 的 URL pattern mock 功能。

標頭參數

標頭參數提供關於所發出請求的額外資訊，通常用於驗證、內容類型與其他中繼資料。

了解更多

深入了解標頭參數。

主體參數

主體參數包含要在請求主體中傳送的資料，通常用於 POST、PUT 和 PATCH 請求，以建立或更新資源。資料通常會以 JSON 或 XML 格式傳送。

了解更多

深入了解主體參數。

描述參數

參數應描述其名稱、類型（字串、整數、布林值等）、必要性（必填或選填），以及任何預設值或限制條件。

描述參數時，通常會使用以下關鍵屬性：

屬性	說明
Name	指定所描述參數的名稱。這是必填欄位，且應準確代表所定義的參數。
Type	指定參數值的資料類型。常見值包括 `string`、`number`、`integer`、`boolean`、`array`、`object` 等。此屬性有助於定義參數值的格式與結構。
Description	提供關於參數的簡要說明或文件。它有助於使用者了解參數的用途與使用方式。
Required	指定此參數是否為 API 請求的必要項目。這是一個布林值（`true` 或 `false`），表示請求中是否必須包含該參數。
Advanced Settings	定義參數的資料類型、格式與限制條件。它允許你提供關於參數值預期結構與內容的詳細資訊。

Type Editor

你可以使用 Type Editor 有效率地修改參數的進階設定。深入了解 Type Editor。

Schemas

當主體參數類型為 JSON 或 XML 時，需要設定資料結構。資料結構可以引用 schemas。

了解更多

如需 schemas 的詳細資訊，請參閱 Schemas。

回應與範例

向 API 傳送請求後，伺服器會返回回應。定義預期回應並提供說明性範例，是提升與你的 API 對接之開發人員理解度與可用性的關鍵步驟。

回傳回應的定義主要包含以下部分：

元件	說明
HTTP Status Code	判定你的端點可能回傳的所有潛在回應狀態，包括標準回應，例如 200 (OK)、404 (Not Found) 或 500 (Server Error)。
Data Format	定義 API 針對每個狀態碼所回傳的回應格式。這可以是 `JSON`、`XML`、`HTML`、`Raw`、`Binary` 或任何其他合適的格式。
Schema	對於攜帶資料的回應（主要是 200 狀態），詳細說明回應 payload 的結構。這包括指定類型、巢狀物件、選填欄位與陣列。清楚的定義有助於用戶端開發人員了解可預期的資料，以及如何解析資料。只有 `JSON` 和 `XML` 可以設定 schemas。如需詳細資訊，請參閱 Schemas。
Example	提供回應範例對於說明 API 在真實情境中的行為至關重要。範例最好是伺服器在端點以預先定義的請求被呼叫時所回傳的範例資料集。它應反映回應 schema 所定義的結構、資料格式與類型。

新增回應

一般來說，建議在你的 API 文件中，為每個端點至少定義一個成功回應與一個錯誤回應。此做法可確保涵蓋各種潛在結果，讓開發人員清楚了解 API 在不同情境下的行為。

按一下 Responses 模組右上角的 + Add 按鈕以新增回應。

通常在 API 設計中，雖然成功的 200 OK 回應經常因不同端點的輸出資料需求不同而有所差異，但錯誤回應（例如 400 Bad Request 和 404 Not Found）往往在不同端點之間保持一致。Apidog 透過其 Response Component 功能聰明地解決了這種共通性，允許重複使用預先定義的錯誤回應，讓 API 文件流程更有效率，並讓 API 行為更一致。

Response Components

深入了解 Response Components。

如果不需要回應元件，你可以選擇 Add Blank Response，以在個別端點中定義獨特回應。

新增回應範例

按一下 "Add Example"，即可在 Apidog 中加入回應範例。

單一回應可以容納多個不同範例。新增範例時，請提供範例名稱與對應的回應資料。

自動產生範例

按一下 Generate Automatically 後，Apidog 會根據回應 schema 定義產生合理的回應資料。

預覽端點

完成端點規格後，按一下 "Save" 以儲存你的變更。接著，切換到 "API" 分頁，以預覽你剛剛設定的端點。

建立端點#

端點路徑#

請求方法#

端點中繼資料#

請求#

請求參數#

查詢參數#

路徑參數#

標頭參數#

主體參數#

描述參數#

Schemas#

回應與範例#

新增回應#

新增回應範例#

自動產生範例#

預覽端點#

建立端點

端點路徑

請求方法

端點中繼資料

請求

請求參數

查詢參數

路徑參數

標頭參數

主體參數

描述參數

Schemas

回應與範例

新增回應

新增回應範例

自動產生範例

預覽端點