NestJS Swagger 模块：自动生成控制器名称作为 API 标签的最佳实践

在构建基于 NestJS 的 RESTful API 时，良好的 API 文档组织对于开发者体验至关重要。NestJS 的 Swagger 模块虽然功能强大，但在 API 分组方面存在一个常见痛点：默认情况下所有路由都被归类到"default"标签下，这在大中型项目中会导致文档难以导航和维护。

问题背景

当开发团队构建包含多个控制器的复杂服务时，Swagger UI 中所有端点混杂在一起会显著降低文档的可读性。虽然可以通过在每个控制器上添加 @ApiTag() 装饰器手动指定分组，但这种做法存在几个问题：

1. 重复劳动：控制器类名本身已经表达了逻辑分组，开发者需要额外维护标签名称
2. 一致性风险：不同开发者可能使用不同的命名约定
3. 维护成本：当重构控制器名称时，需要同步更新标签

解决方案

NestJS Swagger 模块的最新改进引入了一种自动化策略，可以直接使用控制器名称作为 API 标签。这项功能通过 SwaggerCustomOptions 配置实现：

{
  apiTagStrategy: { strategy: 'CONTROLLER_NAME' }
}

这种策略有以下几个显著优势：

1. 零配置：无需在每个控制器上添加额外装饰器
2. 一致性保证：自动保持控制器名称与 API 分组一致
3. 重构友好：重命名控制器时会自动同步更新文档分组

实现原理

在底层实现上，该功能通过以下机制工作：

1. 在 Swagger 文档生成阶段，系统会检查控制器的元数据
2. 如果启用了 CONTROLLER_NAME 策略，系统会使用控制器类名作为 OpenAPI 标签
3. 标签名称会自动进行适当格式化（如去除"Controller"后缀）
4. 开发者仍然可以通过显式的 @ApiTag() 装饰器覆盖自动生成的标签

最佳实践

基于这项新特性，我们推荐以下实践方式：

1. 对于新项目，建议直接启用 CONTROLLER_NAME 策略
2. 对于已有项目，可以逐步迁移：
   • 首先启用新策略
   • 然后逐步移除冗余的 @ApiTag() 装饰器
3. 对于需要特殊分组的情况，仍然可以结合使用手动标签

配置示例

以下是一个完整的配置示例：

// main.ts
const config = new DocumentBuilder()
  .setTitle('API文档')
  .setDescription('API描述')
  .setVersion('1.0')
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document, {
  swaggerOptions: {
    // 其他Swagger UI配置
  },
  apiTagStrategy: { strategy: 'CONTROLLER_NAME' }
});

总结

自动使用控制器名称作为 API 标签的策略显著提升了 NestJS 项目的开发体验和文档质量。这项改进不仅减少了样板代码，还通过强制一致性提高了项目的可维护性。对于任何规模的 NestJS 项目，这都是一种值得采用的文档组织方式。