NestJS Swagger 中路由参数类型对文档生成的影响分析

问题现象

在使用 NestJS Swagger 模块时，发现一个有趣的现象：当控制器方法参数使用非基本类型（如自定义实体类）时，路由参数不会显示在 Swagger UI 中；而使用基本类型（如 string 或 object）时，则能正常显示。

技术背景

NestJS Swagger 模块通过装饰器自动生成 API 文档。@ApiParam() 装饰器用于定义路由参数，而 @Param() 装饰器用于在控制器方法中获取路由参数。

问题复现

正常工作情况

@Controller('/test/:id')
@ApiParam({ name: 'id' })
export class TestController {
    @Get('/')
    public test(@Param('id') qwerty: string) {}
}

这种情况下，Swagger UI 能正确显示 id 参数。

异常工作情况

@Controller('/test/:id')
@ApiParam({ name: 'id' })
export class TestController {
    @Get('/')
    public test(@Param('id') qwerty: User) {}
}

当参数类型为自定义实体类 User 时，Swagger UI 不会显示该路由参数。

技术分析

这个问题的根源在于 NestJS Swagger 模块的类型推断机制。当参数类型为自定义类时，Swagger 模块可能将其视为请求体而非路由参数，导致文档生成出现偏差。

解决方案

根据项目维护者的反馈，该问题已在 master 分支修复，并将随 v8.0.0 版本发布。对于当前版本的用户，可以采取以下临时解决方案：

1. 确保路由参数使用基本类型
2. 显式指定参数类型和位置
3. 使用额外的文档装饰器明确参数信息

最佳实践建议

1. 路由参数尽量使用基本类型
2. 复杂类型建议放在请求体中而非路由参数
3. 保持文档装饰器与实际参数类型一致
4. 考虑升级到最新稳定版本以获得最佳体验

总结

这个问题展示了 API 文档生成工具在处理类型系统时的复杂性。开发者在设计 API 时应当注意参数类型的选用，并在文档生成异常时检查类型定义是否合理。随着 NestJS Swagger 模块的持续更新，这类边界情况问题将得到更好的处理。