NestJS Swagger 中递归模式引用的自定义名称处理问题解析

问题背景

在使用 NestJS 框架开发 API 时，Swagger 模块是一个强大的工具，它能够自动生成 API 文档。然而，在处理递归数据结构时，开发者可能会遇到一个棘手的问题：当使用 @ApiSchema 装饰器为 DTO 类指定自定义名称时，生成的 OpenAPI 文档中的 $ref 引用却错误地使用了类构造函数的原始名称。

问题表现

考虑以下递归 DTO 结构示例：

@ApiSchema({ name: 'MenuNode' })
class MenuNodeDto {
  @ApiProperty({ type: () => MenuNodeDto })
  childNode: MenuNodeDto;
}

@ApiSchema({ name: 'Menu' })
class MenuDto {
  @ApiProperty({ type: () => MenuNodeDto })
  rootNode: MenuNodeDto;
}

开发者期望生成的 OpenAPI 文档中，引用应该使用自定义的名称 MenuNode，但实际上却使用了类构造函数的原始名称 MenuNodeDto，导致文档不正确。

技术原理分析

这个问题的根源在于 NestJS Swagger 模块内部处理模式引用时的逻辑缺陷。具体来说：

1. 当解析递归类型时，系统会调用 createNotBuiltInTypeReference 方法创建类型引用
2. 该方法直接从构造函数获取类型名称，而没有优先考虑 @ApiSchema 装饰器提供的自定义名称
3. 这种处理方式违背了装饰器的设计初衷，导致自定义名称被忽略

解决方案

核心解决方案是修改 createNotBuiltInTypeReference 方法的实现，使其优先从元数据中获取模式名称：

let { schemaName: schemaObjectName } = this.getSchemaMetadata(
  trueMetadataType as Function | Type<unknown>
);

这个修改确保了：

1. 首先检查是否有通过装饰器定义的自定义名称
2. 如果没有自定义名称，才回退到使用构造函数名称
3. 保证了递归引用的一致性

最佳实践建议

1. 显式命名：对于复杂的递归结构，总是使用 @ApiSchema 装饰器显式命名
2. 一致性检查：生成文档后，检查递归引用是否正确指向自定义名称
3. 版本控制：注意 NestJS Swagger 模块的版本更新，确保使用包含此修复的版本

测试验证

为了确保修复的有效性，可以编写如下测试用例：

it('递归引用应正确使用自定义模式名称', () => {
  @ApiSchema({ name: 'CustomNode' })
  class NodeDto {
    @ApiProperty({ type: () => NodeDto })
    child: NodeDto;
  }

  const schemas = {};
  schemaObjectFactory.exploreModelSchema(NodeDto, schemas);

  expect(schemas['CustomNode'].properties['child']['$ref'])
    .toEqual('#/components/schemas/CustomNode');
});

总结

递归数据结构在 API 设计中很常见，NestJS Swagger 模块的这一修复确保了开发者能够完全控制生成的 OpenAPI 文档中的模式名称。理解这一问题的本质有助于开发者更好地利用 NestJS 的装饰器系统，构建更清晰、更一致的 API 文档。