NestJS Swagger 中 ApiProperty 选项导致 allOf 而非 $ref 的问题解析

问题现象

在使用 NestJS 的 Swagger 模块时，当我们在 ApiProperty 装饰器中添加某些选项（如 description 或 nullable）来修饰一个引用其他 DTO 的属性时，生成的 OpenAPI 文档会出现意外的结构变化。具体表现为：

• 预期行为：希望生成简单的 $ref 引用
• 实际行为：生成了包含 allOf 的复杂结构

技术背景

在 OpenAPI 规范中，$ref 和 allOf 是两种不同的引用方式：

1. $ref 用于直接引用已定义的模型
2. allOf 用于组合多个模型或扩展模型

NestJS Swagger 模块的这种行为差异源于 OpenAPI 不同版本对引用对象描述覆盖的支持：

• OpenAPI 3.0.x 不允许在引用对象($ref)上覆盖描述
• OpenAPI 3.1.x 允许在引用对象上覆盖描述

问题复现条件

这个问题会在以下情况下出现：

1. 定义了一个基础 DTO 类（如 SecondLevelDTO）
2. 在另一个 DTO 中引用这个基础 DTO 作为属性类型
3. 在该属性的 ApiProperty 装饰器中添加了会影响 OpenAPI 结构的选项（如 description 或 nullable）

影响分析

这种生成结果虽然技术上正确，但会带来以下问题：

1. 文档结构变得复杂和不直观
2. 可能导致某些 OpenAPI 工具链处理困难
3. 在需要覆盖基础 DTO 描述时缺乏优雅的解决方案

解决方案建议

临时解决方案

1. 对于 description 属性：

   • 避免在引用属性的 ApiProperty 中设置 description
   • 改为在基础 DTO 的 ApiSchema 中统一设置描述
   • 或者创建继承自基础 DTO 的新 DTO 来修改描述

2. 对于 nullable 属性：

   • 目前没有完美的解决方案
   • 可以考虑修改基础 DTO 的设计

长期建议

1. 升级到支持 OpenAPI 3.1.x 的 NestJS Swagger 版本
2. 等待官方修复此问题
3. 在必须覆盖描述的场景下，评估是否真的需要覆盖，还是可以调整 DTO 设计

最佳实践

在设计 Swagger 文档时，建议：

1. 保持 DTO 描述的单一来源
2. 避免在多个地方对同一模型进行描述覆盖
3. 合理使用继承和组合来组织 DTO 结构
4. 在必须覆盖描述时，考虑创建专门的 DTO 变体

总结

这个问题反映了 OpenAPI 规范演进过程中带来的兼容性挑战。作为开发者，我们需要在遵循规范的同时，找到平衡文档清晰度和功能需求的解决方案。理解底层机制有助于我们做出更合理的设计决策。