使用openapi-typescript生成OpenAPI子集类型定义

在开发基于OpenAPI规范的TypeScript项目时，我们经常会遇到只需要部分API接口类型定义的情况。本文将介绍如何利用openapi-typescript工具生成OpenAPI规范的子集类型定义。

需求背景

在实际项目中，一个OpenAPI规范可能包含多种类型的接口：

• 公共API和内部API
• 不同功能模块的API
• 不同权限级别的API

我们可能只需要为其中一部分接口生成TypeScript类型定义，而不是整个API规范。

解决方案

使用Redocly CLI预处理

目前openapi-typescript本身不直接支持过滤功能，但我们可以结合Redocly CLI工具先对OpenAPI规范进行预处理，然后再使用openapi-typescript生成类型定义。

1. 首先安装Redocly CLI：

npm add -D @redocly/cli

2. 创建Redocly配置文件redocly.yaml：

apis:
  main:
    root: http://localhost:43020/api/v1/docs/json
    decorators:
      filter-in:
        property: operationId
        value: [connectRepo]

3. 创建自动化脚本：

REDOCLY_TELEMETRY=off redocly bundle main --config=redocly.yaml -o api.yaml &&
openapi-typescript ./api.yaml -o ./src/api.ts &&
rm ./api.yaml

过滤选项说明

Redocly提供了多种过滤方式：

1. 按operationId过滤：

filter-in:
  property: operationId
  value: [connectRepo, getUser]

2. 按路径过滤：

filter-in:
  property: path
  value: [/api/public/*]

3. 按标签过滤：

filter-in:
  property: tags
  value: [public]

4. 使用自定义属性过滤（如x-area）：

filter-in:
  property: x-area
  value: [feature1, feature2]

注意事项

1. 确保Redocly生成的中间文件格式正确，openapi-typescript才能正常处理。

2. 如果API规范很大，预处理步骤可能会比较耗时。

3. 可以考虑将预处理步骤封装为npm脚本，方便团队共享。

4. 对于持续集成环境，建议缓存预处理结果以提高构建速度。

替代方案

如果不想引入Redocly作为额外依赖，也可以考虑：

1. 手动拆分OpenAPI规范为多个文件，分别生成类型定义。

2. 编写自定义脚本预处理OpenAPI规范。

3. 使用其他OpenAPI工具链如swagger-cli进行预处理。

总结

通过结合Redocly CLI和openapi-typescript，我们可以灵活地生成OpenAPI规范的子集类型定义。这种方法特别适用于大型API项目，或者需要区分不同环境、不同权限级别的类型定义场景。