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 规范扩展

指定端点所属的文件夹#

端点状态#

可用状态值#

维护者#

指定端点所属的文件夹

端点状态

可用状态值

维护者