nestjs/swagger生成OpenApi嵌套对象未自动引用Schema如何解决

算力阿峰

2026-8-26

NestJS Swagger 嵌套对象未生成$ref引用的配置调整方案

出现嵌套属性被扁平化、未自动引用已生成Schema的问题，本质是自定义对象类型的元数据未被Swagger模块正确识别，按以下规则调整即可：

显式声明嵌套对象属性的类型
TS类型在编译后会被擦除，基础类型、枚举可以被Swagger自动推断识别，但自定义对象类型必须在@ApiProperty装饰器中显式传入type字段，否则Swagger会拆解嵌套对象的所有属性平铺到父级层级。
正确写法示例：

export class ParentDto {
  // 基础类型、枚举无需额外声明type即可自动识别
  @ApiProperty()
  baseField: string;

  // 自定义对象类型必须显式声明type，用箭头函数可避免循环依赖问题
  @ApiProperty({ required: false, type: () => MySchema })
  myNestedField?: MySchema;

  // 如果是嵌套对象数组，写法为 type: () => [MySchema]
}

补全未被自动扫描的Schema注册
如果自定义的MySchema没有直接作为接口的请求参数、响应参数类型被Swagger扫描到，需要在初始化Swagger文档时通过extraModels字段显式注册：

const swaggerConfig = new DocumentBuilder().setTitle('接口文档').build();
const document = SwaggerModule.createDocument(app, swaggerConfig, {
  extraModels: [MySchema], // 加入所有未被自动扫描到的自定义Schema
});
SwaggerModule.setup('api', app, document);

排查依赖导入错误
如果使用了PartialType、OmitType、IntersectionType等映射类型工具，必须从@nestjs/swagger包导入，不能从@nestjs/mapped-types导入，后者不会携带Swagger识别所需的元数据，会导致嵌套类型解析异常。
清理错误配置
检查Swagger配置项，不要开启非官方的属性扁平化、深度扫描类自定义配置，避免干扰默认的Schema引用逻辑。