使用openapi-typescript生成OpenAPI规范的子集类型

在开发基于OpenAPI规范的TypeScript项目时，我们经常遇到需要根据不同的使用场景生成不同类型的需求。openapi-typescript项目提供了一个强大的工具，可以将OpenAPI规范转换为TypeScript类型定义，但默认情况下会处理整个API规范。

实际应用场景

在实际项目中，我们可能会遇到以下几种需要生成子集类型的场景：

1. 权限分离：API中部分接口是公开的，部分需要认证
2. 功能模块化：前端只需要特定功能模块的接口类型
3. 性能优化：减少生成的类型定义体积

解决方案探索

虽然openapi-typescript本身不直接支持生成子集类型，但我们可以结合Redocly CLI工具链实现这一需求。Redocly提供了强大的OpenAPI规范处理能力，包括过滤和转换功能。

技术实现步骤

1. 安装Redocly CLI： 首先需要安装Redocly命令行工具作为开发依赖。

2. 创建Redocly配置文件： 配置文件中定义需要保留的接口过滤条件，例如基于operationId、标签或自定义属性。

3. 生成过滤后的规范： 使用Redocly的bundle命令处理原始OpenAPI规范，输出过滤后的临时文件。

4. 生成类型定义： 将过滤后的临时文件作为openapi-typescript的输入，生成最终的TypeScript类型定义。

配置示例

Redocly配置文件示例（redocly.yaml）：

apis:
  main:
    root: http://example.com/api/docs/json
    decorators:
      filter-in:
        property: operationId
        value: [publicEndpoint1, publicEndpoint2]

执行命令序列：

redocly bundle main -o filtered-api.yaml
openapi-typescript filtered-api.yaml -o src/api-types.ts
rm filtered-api.yaml

高级过滤技巧

除了基本的operationId过滤外，Redocly还支持多种过滤方式：

1. 基于标签过滤：可以保留或排除特定标签标记的接口
2. 路径模式匹配：使用正则表达式匹配特定路径模式的接口
3. 自定义属性过滤：利用OpenAPI的扩展属性(x-)实现更灵活的过滤逻辑

注意事项

1. 确保过滤后的规范仍然是有效的OpenAPI文档
2. 考虑将过滤命令集成到项目构建流程中
3. 临时文件的清理工作也很重要，避免污染代码库
4. 对于大型API，过滤可以显著减少生成的类型定义体积

通过这种组合方案，开发者可以灵活地根据项目需求生成精确的TypeScript类型定义，既保持了类型安全，又避免了不必要的类型定义膨胀。