如何解决 OAS 重复路径错误

在使用 OpenAPI 规范（OAS）定义 API 时，"重复路径"错误是最常见的问题之一。本文将帮助您理解这个错误的原因以及如何解决它。

什么是重复路径错误

当您的 OpenAPI 文档中出现两个或多个相同的路径定义时，就会发生重复路径错误。例如：

1paths:
2  /users:
3    get:
4      summary: 获取用户列表
5  /users:
6    post:
7      summary: 创建新用户

这是错误的，因为 /users 路径被定义了两次。

正确的做法

应该将同一路径下的所有 HTTP 方法合并到一个路径定义中：

1paths:
2  /users:
3    get:
4      summary: 获取用户列表
5      responses:
6        '200':
7          description: 成功
8    post:
9      summary: 创建新用户
10      responses:
11        '201':
12          description: 创建成功

常见场景

1. 路径参数重复

1# 错误
2/users/{id}:
3  get:
4    summary: 获取用户
5/users/{userId}:
6  put:
7    summary: 更新用户
8
9# 正确
10/users/{id}:
11  get:
12    summary: 获取用户
13  put:
14    summary: 更新用户

2. 带斜杠和不带斜杠的路径

1# 这会被视为两个不同路径
2/users
3/users/

建议统一使用不带斜杠的格式。

工具支持

许多工具可以帮助您检测重复路径：

• Swagger Editor 会显示验证错误
• OpenAPI Generator 会在构建时检查
• 各种 IDE 插件提供实时验证

预防措施

1. 使用模块化方式组织 OpenAPI 文档
2. 实施代码审查流程
3. 在 CI/CD 中集成验证步骤
4. 使用 API 管理平台集中管理规范