OpenAPI-Typescript 中可选路径参数的处理与最佳实践

背景介绍

在使用 OpenAPI-Typescript 项目中的 openapi-fetch 库时，开发者可能会遇到一个关于可选路径参数的有趣问题。根据 OpenAPI 3.0 规范，路径参数本质上是必须的，但在实际业务场景中，我们有时确实需要实现类似"可选路径参数"的功能。

问题本质

在 RESTful API 设计中，有时我们希望某些路径段成为可选的。例如：

• /api/box/create - 创建一个新盒子
• /api/box/create/1234 - 基于 ID 为 1234 的盒子创建新盒子

开发者尝试通过将路径参数标记为 nullable: true 或传递 undefined/null 值来实现这一功能，但这与 OpenAPI 规范存在冲突。

OpenAPI 规范解读

根据 OpenAPI 3.0 规范：

1. 路径参数必须设置 required: true（这是规范强制要求的）
2. allowEmptyValue 属性仅适用于查询参数，不能用于路径参数
3. 路径参数不支持真正的"可选"概念

解决方案

方案一：设计两个独立路径

最符合规范的做法是为每个变体定义独立路径：

/api/box/create:
  post:
    # 创建新盒子的定义
    
/api/box/create/{source}:
  post:
    # 基于现有盒子创建的定义

方案二：使用查询参数替代

考虑将可选参数改为查询参数：

/api/box/create?source=1234

方案三：特殊值处理（临时方案）

如果必须使用路径参数，可以：

1. 使用空字符串作为特殊值（不推荐，违反规范）
2. 使用特定值如 "new" 表示无源盒子

技术实现细节

在 openapi-fetch 库中，路径参数的序列化逻辑会检查值是否为 undefined 或 null，如果遇到这些值会抛出错误。这是为了严格执行 OpenAPI 规范的要求。

最佳实践建议

1. 遵循规范设计：优先考虑使用两个独立端点或查询参数
2. 文档清晰：无论采用哪种方案，确保API文档明确说明不同场景的使用方式
3. 一致性：在整个API中保持参数传递方式的一致性
4. 客户端处理：在客户端代码中封装不同场景的调用逻辑，提供清晰的接口

总结

虽然开发者有时需要实现"可选路径参数"的功能，但严格遵守 OpenAPI 规范能带来更好的互操作性和可维护性。通过合理设计多个端点或使用查询参数，可以既满足业务需求又保持规范兼容性。