OpenAPI TypeScript 项目中排除弃用参数的实现问题分析

在 OpenAPI TypeScript 项目中，开发者发现了一个关于参数过滤的重要问题：当使用 --exclude-deprecated 标志时，弃用(deprecated)的查询参数(query parameters)和路径参数(path parameters)没有被正确排除。

问题背景

OpenAPI 规范允许开发者通过设置 deprecated: true 来标记某些参数为弃用状态。在生成 TypeScript 类型定义时，项目提供了 --exclude-deprecated 标志来过滤掉这些弃用的参数，以保持生成的类型定义干净整洁。

然而，在实际使用中发现，虽然这个标志对响应体(response body)中的弃用字段有效，但对于查询参数和路径参数却不起作用。这意味着即使标记了 deprecated: true，这些参数仍然会出现在生成的类型定义中。

技术细节分析

从技术实现角度来看，这个问题源于操作对象(operation object)转换器中对参数的处理逻辑不够完善。在当前的实现中，虽然能够识别参数的弃用状态并添加 @deprecated 注释，但并没有在 --exclude-deprecated 标志启用时真正过滤掉这些参数。

以查询参数为例，一个典型的 OpenAPI 定义可能如下：

parameters:
  - schema:
      type: string
    deprecated: true
    in: query
    name: id

理想情况下，当启用 --exclude-deprecated 时，生成的类型定义应该完全排除这个 id 参数。但实际输出却保留了该参数，只是添加了弃用注释。

解决方案

解决这个问题的关键在于修改操作对象转换器中的参数处理逻辑。具体需要：

1. 在转换参数对象时，检查 --exclude-deprecated 标志是否启用
2. 如果标志启用，则过滤掉所有标记为 deprecated: true 的参数
3. 确保过滤操作同时适用于查询参数、路径参数等所有参数类型

这种修改保持了向后兼容性，因为当不启用 --exclude-deprecated 标志时，行为与之前完全一致。

对开发者的影响

这个问题的修复将带来以下好处：

1. 更干净的API接口定义：开发者可以确保弃用的参数不会出现在类型系统中
2. 更好的代码维护性：团队可以放心地标记弃用参数，而不用担心它们会污染代码库
3. 更一致的开发体验：所有类型的弃用参数(查询、路径等)都将被一致处理

对于使用 OpenAPI TypeScript 生成前端类型定义的项目来说，这个修复将显著提升开发体验和代码质量。

总结

OpenAPI TypeScript 项目中的这个参数过滤问题虽然看似简单，但却影响着生成的类型定义的质量。通过修复这个问题，项目将提供更强大、更一致的弃用参数处理能力，帮助开发者构建更健壮的API客户端代码。