NestJS Swagger模块中ApiTags重复显示问题解析

问题现象

在使用NestJS框架开发RESTful API时，开发者可能会遇到Swagger UI界面中显示的API标签数量与代码中实际定义的数量不一致的情况。具体表现为：在控制器中明明只给两个路由方法添加了@ApiTags()装饰器，但在生成的Swagger文档中却显示了四个标签分类。

问题根源

这个现象实际上是由Swagger模块的默认配置行为导致的。NestJS的Swagger模块在生成文档时，会默认启用"tags"分组功能。当没有显式配置时，系统会自动根据控制器(Controller)名称和手动添加的@ApiTags()装饰器来生成标签分类。

解决方案

要解决这个问题，开发者可以通过修改Swagger文档配置来禁用自动标签分组功能。在Swagger模块初始化时，可以设置useTags选项为false：

const options = new DocumentBuilder()
  .setTitle('API文档')
  .setDescription('API描述')
  .setVersion('1.0')
  .addTag('cats')
  .addTag('Authentication')
  .build();

const document = SwaggerModule.createDocument(app, options, {
  useTags: false  // 禁用自动标签分组
});

深入理解

1. 标签分组机制：Swagger的标签功能主要用于对API进行逻辑分组，方便开发者查看和管理。当启用自动分组时，系统会：

   • 为每个控制器自动创建一个标签
   • 同时保留开发者手动添加的标签
   • 导致标签数量多于预期

2. 设计考量：这种默认行为实际上是为了提供更灵活的文档组织方式。在大型项目中，开发者可能希望同时使用控制器分组和功能分组两种维度来组织API文档。

3. 最佳实践：

   • 小型项目：可以禁用自动分组，完全手动控制标签
   • 大型项目：可以利用自动分组+手动标签的组合方式
   • 混合使用：某些控制器使用自动分组，某些使用手动标签

扩展知识

除了useTags选项外，Swagger模块还提供了其他相关配置：

1. 深度控制：可以通过deepScanRoutes选项控制是否深度扫描路由
2. 额外模型：使用extraModels可以添加额外的DTO模型
3. 忽略属性：通过ignoreGlobalPrefix可以控制是否忽略全局路由前缀

理解这些配置选项可以帮助开发者更精确地控制生成的Swagger文档结构和内容，打造更符合项目需求的API文档。