Apidog OpenAPI 規格擴充

Apidog 支援自訂 OpenAPI/Swagger 規格擴充，可增強 API 設計與管理能力。這些擴充允許你為 API 端點指定額外的中繼資料，例如資料夾組織、端點狀態和維護者資訊。

本參考指南記錄了可在 OpenAPI/Swagger 規格中使用的自訂 x-apidog-* 擴充，以便與 Apidog 的功能無縫整合。

指定端點所屬的資料夾

Apidog 會優先使用 x-apidog-folder 欄位來組織端點。如果此欄位不存在，則會使用 tags 欄位中的第一個值。

使用斜線 / 分隔多層級資料夾。請注意，反斜線 \ 和正斜線 / 都是需要跳脫的特殊字元。若要表示正斜線 / 字元，請使用 \/；若要表示 \ 字元，請使用 \\。

範例：

"paths": {
  "/pets": {
     "post": {
         ...
         "operationId": "addPet",     
         "x-apidog-folder": "Pet Store/Pet Information"
     }
  }
}

Swagger 註解範例：

資料夾組織

使用具描述性的資料夾名稱，以邏輯方式組織你的端點。這可改善導覽，並幫助團隊成員快速找到端點。

端點狀態

使用 x-apidog-status 欄位檢查端點的狀態。這可讓你追蹤每個 API 端點的開發生命週期。

可用的狀態值

狀態	說明
designing	（設計中）
pending	（待處理）
developing	（開發中）
integrating	（整合中）
testing	（測試中）
tested	（已測試）
released	（已發布）
deprecated	（已棄用）
exception	（例外）
obsolete	（已淘汰）
to be deprecated	（即將棄用）

範例：

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",     
            "x-apidog-status": "released"
        }
    }
}

Swagger 註解範例：

狀態追蹤

端點狀態可幫助團隊協調開發工作，並了解哪些 API 已準備好用於正式環境。

維護者

使用 x-apidog-maintainer 欄位指定端點的維護者。其值為團隊中 Apidog 使用者的暱稱或使用者名稱。

範例：

"paths": {
    "/pets": {
        "post": {
            ...   
            "x-apidog-maintainer": "david"
        }
    }
}

Swagger 註解範例：

重要

維護者值必須符合 Apidog 中現有團隊成員的使用者名稱或暱稱，才能正確指派。

Apidog OpenAPI 規格擴充

指定端點所屬的資料夾#

端點狀態#

可用的狀態值#

維護者#

指定端點所屬的資料夾

端點狀態

可用的狀態值

維護者