NestJS Swagger 模块中枚举默认值的最佳实践

在 NestJS 项目中，Swagger 模块是一个强大的工具，用于自动生成 API 文档。然而，在使用枚举(enum)类型时，开发者经常会遇到一个常见问题：当使用 enumName 属性引用枚举时，默认值(default)会丢失。

问题现象

当开发者使用 @ApiProperty 装饰器定义枚举属性时，通常会遇到两种不同的行为：

1. 直接定义枚举：

@ApiProperty({ enum: SortOrder, default: SortOrder.DESC })

这种方式会正确生成包含默认值的 OpenAPI 规范。

2. 使用 enumName 引用枚举：

@ApiProperty({ enum: SortOrder, default: SortOrder.DESC, enumName: 'SortOrder' })

这种方式生成的 OpenAPI 规范中，默认值会丢失。

技术背景

这个问题的根源在于 OpenAPI 规范本身的设计。当使用 $ref 引用一个模式(schema)时，根据 OpenAPI 3.0 规范，引用对象不能包含其他属性。这意味着一旦我们使用 enumName 创建引用，所有其他属性(包括 default)都会被忽略。

解决方案

目前社区提出了几种解决方案：

1. 使用 allOf 组合模式：

@ApiProperty({ 
  default: SortOrder.DESC,
  allOf: [
    { $ref: getSchemaPath('SortOrder') },
  ]
})

这种方式利用了 OpenAPI 的组合特性，既保留了引用，又能添加额外属性。

2. 修改 SchemaObjectFactory： 一些开发者通过修改 NestJS Swagger 的内部实现，将 $ref 包装在 allOf 中，从而保留其他属性。

3. 接受默认值在枚举定义中： 另一种做法是将默认值定义在枚举本身的模式中，而不是在引用处。

最佳实践建议

1. 对于简单的枚举使用场景，可以直接在 @ApiProperty 中定义 enum 和 default，不使用 enumName。

2. 当需要在多处重用同一个枚举时，建议使用 allOf 组合模式，这样可以保持文档的清晰性和一致性。

3. 考虑在枚举定义处添加默认值，这样无论在哪里引用，都能保持一致的默认行为。

4. 对于复杂的 API 文档需求，可以创建自定义装饰器或工具函数来简化重复的模式定义。

未来展望

随着 OpenAPI 规范的演进，未来版本可能会提供更优雅的方式来解决这个问题。目前 NestJS Swagger 团队已经注意到这个问题，并可能在未来的版本中提供官方解决方案。

在实际开发中，理解这些底层机制有助于开发者做出更明智的技术选择，创建出更健壮、更易维护的 API 文档。