如何为@nestjs/swagger控制器添加描述信息？

适配版本操作步骤 #

@nestjs/swagger v7及以上版本（对应Nest 9+官方推荐版本） #

直接在控制器类上方使用@ApiTags装饰器，传入配置对象同时指定标签名称和描述即可生效：

import { Controller, Get, Param } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';

// 控制器级描述配置
@ApiTags({
  name: '用户管理',
  description: '包含用户增删改查、权限配置相关接口'
})
@Controller('users')
export class UsersController {
  // 单接口描述配置
  @Get(':id')
  @ApiOperation({
    summary: '获取单个用户信息',
    description: '根据传入的用户ID查询对应用户完整信息，需管理员权限调用'
  })
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(+id);
  }
}

@nestjs/swagger v6及以下版本 #

需要在Swagger初始化配置中通过addTag方法配置标签对应的描述，再在控制器上关联对应标签即可：

1. main.ts中配置标签描述：

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('接口文档')
    .setDescription('项目API文档')
    .setVersion('1.0')
    .addTag('用户管理', '包含用户增删改查、权限配置相关接口')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
  await app.listen(3000);
}
bootstrap();

2. 控制器上关联标签：

@ApiTags('用户管理')
@Controller('users')
export class UsersController {}

失效排查 #

• 配置修改后需重启服务，同时清除浏览器缓存，避免旧的Swagger页面缓存导致描述不生效
• 确保安装的@nestjs/swagger版本和Nest核心版本兼容，避免版本不匹配导致装饰器失效

内容的提问来源于stack exchange，提问作者Stanislav