hey-api/openapi-ts 0.67.0版本发布：TypeScript模块解析与Discriminator字段优化

项目简介

hey-api/openapi-ts是一个用于将OpenAPI/Swagger规范转换为TypeScript代码的工具，它能够自动生成强类型的客户端代码，帮助开发者更安全、高效地与API进行交互。该项目特别适合需要与RESTful API频繁交互的前端或Node.js项目。

版本亮点

1. 支持tsconfig.json中的moduleResolution配置

在0.67.0版本中，工具现在能够正确识别并应用项目tsconfig.json文件中的moduleResolution设置。这一改进特别针对使用Node.js原生ES模块系统的项目。

当moduleResolution设置为"nodenext"时，工具会自动在相对模块路径后添加.js扩展名，这是Node.js ES模块规范的要求。例如：

// 之前
import { Api } from './api';

// 现在（当moduleResolution为nodenext时）
import { Api } from './api.js';

如果开发者希望保持之前的行为（不自动添加.js扩展名），可以通过配置output.tsConfigPath为"off"来禁用此功能：

export default {
  input: 'your-openapi-spec',
  output: {
    path: 'src/client',
    tsConfigPath: 'off', // 禁用自动添加.js扩展名
  },
};

这一改进使得生成的代码能够更好地与现代JavaScript模块系统兼容，特别是在Node.js环境中使用原生ES模块时。

2. 修复oneOf与discriminator组合使用时的字段必填问题

在OpenAPI规范中，discriminator字段常用于区分使用oneOf组合的不同模型。0.67.0版本修复了一个重要问题：现在当discriminator字段与oneOf关键字一起使用时，该字段会被正确地标记为必填字段。

例如，考虑以下OpenAPI定义：

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

在之前的版本中，生成的TypeScript类型可能不会强制要求petType字段。而在0.67.0版本中，petType会被正确地标记为必填字段，确保了类型安全。

3. 类型名称生成优化

该版本还改进了生成类型名称时的处理逻辑，特别是对于附加类型（如data、error、response等）的命名。现在工具会避免在这些附加类型前添加下划线，使得生成的类型名称更加整洁和一致。

例如，之前可能生成的类型名称为_Data或_Error，现在会直接生成Data或Error，提高了代码的可读性。

升级建议

对于正在使用hey-api/openapi-ts的项目，特别是以下情况建议升级到0.67.0版本：

1. 项目使用Node.js的ES模块系统（moduleResolution设置为nodenext）
2. API设计中使用了oneOf和discriminator组合来区分不同类型
3. 希望生成的类型名称更加简洁一致

升级时需要注意：

• 如果项目依赖不自动添加.js扩展名的行为，记得配置tsConfigPath为"off"
• 检查是否有代码依赖于之前discriminator字段非必填的行为，可能需要相应调整

这个版本的改进使得生成的TypeScript代码更加符合现代JavaScript模块系统的要求，同时在类型安全方面也有所增强，是值得推荐的一次升级。