NestJS Swagger 中 oneOf 属性的使用与注意事项

背景介绍

在 NestJS 项目中，Swagger 模块用于自动生成 API 文档。其中，@ApiProperty 装饰器可以用来定义模型属性的各种元数据，包括数据类型、描述信息等。在最新版本中，关于 oneOf 属性的使用方式发生了一些变化，这可能会影响开发者的使用体验。

问题现象

在 NestJS Swagger v6 版本中，开发者可以使用以下方式定义一个可以是字符串数组、数字数组或布尔值数组的属性：

@ApiProperty({
  type: undefined,
  oneOf: [
    { type: 'array', items: { type: 'string' } },
    { type: 'array', items: { type: 'number' } },
    { type: 'array', items: { type: 'boolean' } },
  ],
  description: 'API描述信息',
})
values: string[] | number[] | boolean[];

这种方式在 v6 版本中会生成预期的 OpenAPI 规范，其中 values 属性被正确地定义为三种可能的数组类型之一。

版本升级后的变化

升级到 NestJS Swagger v7 后，相同的代码会生成不同的 OpenAPI 规范。主要变化是 type: array 被自动添加，而 oneOf 的定义方式也发生了变化，不再像 v6 那样直接定义 values 的 schema。

解决方案

经过实践，发现可以通过以下方式解决这个问题：

type Values = string[] | number[] | boolean[];

@ApiProperty({
  type: undefined,
  oneOf: [
    { type: 'array', items: { type: 'string' } },
    { type: 'array', items: { type: 'number' } },
    { type: 'array', items: { type: 'boolean' } },
  ],
  description: 'API描述信息',
})
values: Values;

通过将联合类型提取为一个单独的类型别名，可以确保在 v7 版本中生成正确的 OpenAPI 规范。

技术原理分析

这种变化可能与 NestJS Swagger 在 v7 版本中对类型系统的处理方式改进有关。在 v7 中，类型推断机制可能更加严格，直接使用联合类型可能会导致一些意外的行为。通过使用类型别名，可以更明确地表达开发者的意图，从而生成正确的 OpenAPI 规范。

最佳实践建议

1. 对于复杂的联合类型，建议使用类型别名而不是直接内联
2. 升级到 v7 后，检查所有使用 oneOf 的地方，确保生成的文档符合预期
3. 在定义数组类型的 oneOf 时，明确指定 type: 'array' 和 items 属性

总结

NestJS Swagger v7 在类型处理上做了一些改进，这可能导致一些在 v6 中工作的代码需要调整。通过使用类型别名等更明确的类型定义方式，可以确保生成的 OpenAPI 文档符合预期。开发者应该注意这些变化，并在升级后进行适当的代码调整。