3 nestjs 集成 Swagger

安装依赖

pnpm install @nestjs/swagger class-validator

在 main.ts 中定义 SwaggerModule 类

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('water-admin')
    .setDescription('Background system based on Nest.js + Vue3 full stack')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // 设置swagger的地址url： /api
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}

bootstrap();

方法	描述
setTitle	文档标题
setDescription	文档描述
setVersion	文档版本
setTermsOfService	文档服务条款
setContact	文档联系信息
setLicense	文档许可证信息
addServer	文档服务地址
setExternalDoc	文档外部链接
setBasePath	设置文档基础路径
addTag	添加文档标签
addExtension	添加扩展
addSecurity	添加安全方案
addGlobalParameters	添加全局参数
addSecurityRequirements	添加安全需求
addBearerAuth	添加 Bearer Token 认证
addOAuth2	添加 OAuth2 认证
addApiKey	添加 ApiKey
addBasicAuth	添加基础认证
addCookieAuth	添加 Cookie 认证
build	构建服务

在 DTO 中使用装饰器

import { ApiProperty } from '@nestjs/swagger';
import { IsNumberString, IsOptional, IsUUID } from 'class-validator';

export class CreateWaterDto {
  @ApiProperty({
    type: String,
    description: '岗位名称',
    required: false,
    default: '前端工程师',
  })
  name?: string;

  @ApiProperty({
    type: String,
    description: '所属组织',
    default: 'f45cd48b-e703-49db-91be-ae7f594e73e0',
    required: false,
  })
  @IsOptional()
  @IsUUID('all', { message: 'orgId 参数不正确' })
  orgId?: string;

  @ApiProperty({
    type: Number,
    description: '开始日期',
    default: 1721145600000,
    required: false,
  })
  @IsOptional()
  @IsNumberString({}, { message: '开始日期必须是时间戳格式' })
  startTime?: number;

  @ApiProperty({
    type: Number,
    description: '结束日期',
    default: 1721318399999,
    required: false,
  })
  @IsOptional()
  @IsNumberString({}, { message: '结束日期必须是时间戳格式' })
  endTime?: number;
}

在 Controller 控制器 中使用装饰器

import {
  Controller,
  Get,
  Post,
  Body,
  Patch,
  Param,
  Delete,
} from '@nestjs/common';
import { WaterService } from './water.service';
import { CreateWaterDto } from './dto/create-water.dto';
import { UpdateWaterDto } from './dto/update-water.dto';
import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';

@ApiTags('岗位管理')
@Controller('water')
export class WaterController {
  constructor(private readonly waterService: WaterService) {}

  @Post()
  @ApiOkResponse({ type: CreateWaterDto })
  @ApiOperation({ summary: '获取岗位管理列表' })
  create(@Body() createWaterDto: CreateWaterDto) {
    return 'ff------ 火箭 🚀';
  }

  @Get()
  findAll() {
    return this.waterService.findAll();
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.waterService.findOne(+id);
  }

  @Patch(':id')
  update(@Param('id') id: string, @Body() updateWaterDto: UpdateWaterDto) {
    return this.waterService.update(+id, updateWaterDto);
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return this.waterService.remove(+id);
  }
}

常用 Swagger 装饰器

装饰器	描述
@ApiTags	为控制器或方法添加标签，用于组织 Swagger UI 文档
@ApiOperation	为控制器方法添加操作描述，包括摘要和详细描述
@ApiParam	描述路径参数、请求参数或响应参数，包括名称、类型、描述等
@ApiBody	指定请求体的 DTO 类型，用于描述请求体的结构
@ApiResponse	描述 API 的响应，包括状态码、描述等
@ApiBearerAuth	指定请求需要携带 Bearer Token，用于身份验证
@ApiProperty	为 DTO 类型的属性添加元数据，如描述、默认值等
@ApiQuery	描述查询参数，包括名称、类型、描述等
@ApiHeader	描述请求头信息，包括名称、类型、描述等
@ApiExcludeEndpoint	标记一个控制器方法不在 Swagger UI 中显示