OpenAPI-Typescript 中处理可选路径参数的技术探讨

在 OpenAPI-Typescript 项目中，开发者遇到了一个关于路径参数处理的常见问题：如何正确处理 OpenAPI 规范中的可选路径参数。这个问题在 REST API 设计中颇具代表性，值得我们深入探讨。

问题背景

在 REST API 设计中，有时会遇到需要将路径中的某些部分设计为可选的情况。例如，一个创建盒子的接口可能有以下两种形式：

1. /api/box/create - 创建一个全新的盒子
2. /api/box/create/1234 - 基于 ID 为 1234 的盒子创建新盒子

开发者期望通过传递 null 或 undefined 来移除路径参数，但发现当前实现中这会导致路径段保留而非被移除。

技术分析

OpenAPI 3.0 规范明确规定：

1. 路径参数必须标记为 required: true
2. allowEmptyValue 属性仅适用于查询参数，不适用于路径参数

这意味着从规范层面，路径参数本质上不支持真正的"可选"概念。当前 openapi-fetch 的实现遵循了这一规范，通过检查参数值是否为 undefined 或 null 来保留路径段。

解决方案比较

方案一：修改规范设计

最符合 OpenAPI 规范的做法是将这两种情况设计为两个独立路径：

/api/box/create:
  post:
    # 创建新盒子的定义

/api/box/create/{source}:
  post:
    # 基于现有盒子创建的定义
    parameters:
      - name: source
        in: path
        required: true
        schema:
          type: integer

优点：

• 完全符合 OpenAPI 规范
• 语义清晰，两种操作明确区分
• 可以利用 $ref 减少重复定义

缺点：

• 需要修改现有 API 规范
• 增加了路径数量

方案二：使用空字符串作为替代

当前可行的临时解决方案是传递空字符串：

client.POST("/api/box/create/{source}", {
  params: { path: { source: "" } }
});

优点：

• 无需修改现有实现
• 能够达到移除路径段的效果

缺点：

• 不符合 OpenAPI 规范
• 可能引起混淆，不够直观

最佳实践建议

1. 遵循规范优先：尽可能按照 OpenAPI 规范设计 API，使用多个明确路径而非可选路径参数

2. 保持一致性：如果确实需要可选路径参数，建议在团队内统一使用空字符串作为标准做法

3. 文档说明：对于特殊处理方式，应在项目文档中明确说明，避免后续维护困惑

4. 考虑长期维护：临时解决方案应标记为待重构，计划在未来版本中迁移到规范兼容的实现

总结

OpenAPI-Typescript 项目当前的行为是正确的规范实现。开发者面临的挑战实际上源于 API 设计决策与 OpenAPI 规范之间的差异。理解规范约束并据此调整 API 设计，才是长期可持续的解决方案。