元件 - Apidog Docs

通常在 API 設計中，雖然成功的 200 OK 回應會因不同端點的輸出資料需求而有所差異，但像 400 Bad Request 和 404 Not Found 這類錯誤回應，往往在不同端點之間保持一致。

Apidog 透過其 回應元件 功能巧妙地處理了這種共通性，允許重複使用預先定義的錯誤回應，使 API 文件流程更有效率，並讓 API 行為更加一致。

OAS 相容性

Apidog 中的回應元件功能與 OAS 中的 Components 相容。

新增回應元件

在 APIs 模組左側目錄樹中，前往 Components 區段，然後點擊 Responses 下的 New Response 以建立新的回應元件。

建立回應元件與定義端點時指定回應區段類似，包含 HTTP 狀態碼、Content type、Schema 和 Examples。如需詳細指引，請參閱 Endpoint Basics 中的 Response 區段。

預設新增至新端點：當選擇為「Yes」時，此元件將會預設自動包含在專案中所有新增的端點內。

INFO

現有端點不會受到此設定影響。

在端點的 Response 區段中，你可以參照預先定義的回應元件。

關於被參照元件的重點：

被參照的回應元件無法在端點內修改。你必須對原始回應元件進行變更。任何修改都會影響所有參照此元件的端點。

如果你想修改已在端點中被參照的回應元件，可以對其執行 Dereference。取消參照會將該回應轉換為一般可編輯的回應，之後回應元件的變更將不再影響它。

在一個端點中，一個元件只能被參照一次；同一個元件的多個實例無法在同一端點內共存。

你可以批次將現有的回應元件新增到選取的端點，或從選取的端點中批次移除此元件。

注意事項：

如果選取的端點已包含此回應元件，則不會再次新增。

如果選取的端點不包含此回應元件，移除動作將不會生效。

許多公司對其回應都有標準化的結構。在這種情況下，你可以利用 預設回應範本，將公司的固定結構維持為預設回應範本。

在左側目錄樹的 Components 區段下，你可以存取並使用 Default Response Template 功能。

建立新端點時，會使用此範本的內容作為初始回應。

主要特性：

對預設回應範本所做的變更只會影響新端點，現有端點不會受到影響。

只存在一個預設回應範本，無法新增或移除。

初始的預設回應範本是一個 200 Success Response，Content type 為 JSON，資料結構為空的 Object 節點。

Q：我可以將回應元件用作預設回應嗎？

A：不可以，回應元件適用於 400、404 及類似狀態碼的通用錯誤回應。如果你需要使用固定的預設回應，請使用預設回應範本。