NestJS Swagger 中枚举数组的引用问题解析

问题背景

在使用 NestJS 框架开发 API 时，我们经常会结合 Swagger 来生成 API 文档。在定义枚举类型时，开发者可能会遇到一个常见问题：当枚举作为单个属性时，Swagger 文档会正确地生成引用（$ref），但当枚举作为数组元素时，Swagger 却会展开枚举的所有可能值，而不是使用引用。

问题现象

考虑以下示例代码：

export enum Animal {
  CAT = 'CAT',
  DOG = 'DOG',
  GOAT = 'GOAT',
}

export class RequestDto {
  @ApiProperty({ enum: Animal, enumName: 'Animal' })
  singleAnimalEnum: Animal;

  @ApiPropertyOptional({
    name: 'listAnimalEnum',
    enum: Animal,
    isArray: true,
  })
  listAnimalEnum: Animal[];
}

生成的 Swagger 文档中，singleAnimalEnum 会正确地使用 $ref 引用 Animal 枚举，而 listAnimalEnum 则会展开所有枚举值：

parameters:
  - name: singleAnimalEnum
    schema:
      $ref: '#/components/schemas/Animal'
  - name: listAnimalEnum
    schema:
      type: array
      items:
        type: string
        enum: [CAT, DOG, GOAT]

解决方案

要解决这个问题，我们需要在数组属性的 @ApiProperty 或 @ApiPropertyOptional 装饰器中明确指定 enumName 属性：

@ApiPropertyOptional({
  name: 'listAnimalEnum',
  enum: Animal,
  isArray: true,
  enumName: 'Animal'  // 关键点：添加这一行
})
listAnimalEnum: Animal[];

这样修改后，Swagger 文档就会正确地使用引用而不是展开枚举值：

parameters:
  - name: listAnimalEnum
    schema:
      type: array
      items:
        $ref: '#/components/schemas/Animal'

技术原理

这个问题的根源在于 Swagger 规范对于枚举类型的处理方式。当没有明确指定 enumName 时，NestJS Swagger 模块会认为这是一个匿名枚举，因此会直接展开枚举值。而指定了 enumName 后，Swagger 模块就能识别出这是一个已定义的枚举类型，从而生成引用。

最佳实践

1. 始终为枚举类型定义名称：即使不用于数组，为枚举类型定义名称也能提高文档的可读性。

2. 保持一致性：在项目中统一使用 enumName，避免部分枚举使用引用而部分展开的情况。

3. 考虑可维护性：使用引用而不是展开枚举值，可以在枚举值变更时只需要修改一处定义。

4. 文档注释：为枚举类型添加详细的文档注释，这些注释也会被包含在生成的 Swagger 文档中。

总结

在 NestJS 中使用 Swagger 时，正确处理枚举数组的引用问题可以显著提高 API 文档的质量和可维护性。通过简单地添加 enumName 属性，我们就能确保生成的文档结构更加清晰和专业。这个小技巧虽然简单，但对于保持大型项目中 API 文档的一致性非常有帮助。