OpenAPI TypeScript 中排除已弃用字段的问题分析与修复

在 OpenAPI TypeScript 项目中，开发者发现了一个关于--exclude-deprecated标志未正确应用于查询和路径参数的问题。本文将深入分析该问题的技术细节、影响范围以及解决方案。

问题背景

OpenAPI TypeScript 是一个将 OpenAPI/Swagger 规范转换为 TypeScript 类型的工具。它提供了一个--exclude-deprecated标志，用于在生成的类型中排除标记为已弃用的字段。然而，在实际使用中发现，该标志对查询参数(query parameters)和路径参数(path parameters)并未生效。

问题表现

当使用包含已弃用查询参数的 OpenAPI 规范时，生成的 TypeScript 类型仍然包含这些已弃用字段。例如：

paths:
  "some_path":
    get:
      parameters:
        - schema:
            type: string
          deprecated: true
          in: query
          name: id

预期生成的类型应该完全排除id字段，但实际上该字段仍被包含在输出中，仅被标记为@deprecated注释。

技术分析

该问题的根源在于操作对象(operation object)转换器未正确处理参数对象的已弃用标志。在当前的实现中，虽然模式(schema)级别的已弃用字段会被排除，但参数级别的已弃用标志却被忽略。

解决方案

修复此问题需要在操作对象转换器中添加对参数对象已弃用标志的检查。具体来说，在转换参数时，应该：

1. 检查每个参数是否标记为已弃用
2. 如果--exclude-deprecated标志启用且参数已弃用，则跳过该参数
3. 确保路径参数和查询参数都受到相同处理

实现建议

在操作对象转换器中，应该在处理参数数组时添加过滤逻辑，类似于：

if (excludeDeprecated && param.deprecated) {
  continue;
}

这将确保所有已弃用的参数，无论它们是路径参数还是查询参数，都会被正确排除在生成的类型之外。

影响评估

此修复将影响所有使用--exclude-deprecated标志并包含已弃用参数的项目。修复后，这些项目的生成类型将更加准确，完全排除已弃用的参数，而不仅仅是添加弃用注释。

最佳实践

对于使用 OpenAPI TypeScript 的开发者，建议：

1. 定期检查生成的类型是否符合预期
2. 对于重要的 API 变更，考虑编写测试来验证生成的类型
3. 在升级工具版本时，注意检查已弃用字段的处理行为是否发生变化

通过理解这个问题及其解决方案，开发者可以更好地利用 OpenAPI TypeScript 工具来管理他们的 API 类型定义，确保生成的代码质量符合项目要求。