Nest.js 实战 (三)：使用 Swagger 优雅地生成 API 文档

什么是 Swagger ?

Swagger 是一组围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具 包括：

• Swagger Editor：基于浏览器的编辑器，您可以在其中编写 OpenAPI 定义
• Swagger UI：将 OpenAPI 定义呈现为交互式文档
• Swagger Codegen：从 OpenAPI 定义中生成服务器存根和客户端库
• Swagger Editor Next（beta）：基于浏览器的编辑器，您可以在其中编写和查看 OpenAPI 和 AsyncAPI 定义
• Swagger Core：用于创建、使用和处理 OpenAPI 定义的 Java 相关库
• Swagger Parser：用于解析 OpenAPI 定义的独立库
• Swagger APIDom：提供了一个单一的、统一的结构，用于跨各种描述语言和序列化格式描述 API

Nest 集成 Swagger

1. 安装依赖

pnpm add @nestjs/swagger swagger-ui-express

2. 在 main.ts 文件中定义并初始化 SwaggerModule 类

 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);// 构建swagger文档const options = new DocumentBuilder().setTitle('vue3-admin').setDescription('Background system based on Nest.js + Vue3 full stack development').setVersion('1.0').build();const document = SwaggerModule.createDocument(app, options);SwaggerModule.setup('docs', app, document);await app.listen(3000);}bootstrap();

3. 启动服务，访问http://localhost:3000/docs，你会看到 Swagger 页面：
   

DocumentBuilder 属性

方法	描述
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	构建服务

在 Nest 中使用

1. 在 DTO(响应数据传输对象) 文件中使用装饰器

 import { ApiProperty } from '@nestjs/swagger';import { IsNumberString, IsOptional, IsUUID } from 'class-validator';export class PostParamsDto {@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;}

2. 在 Controller 控制器 中使用装饰器

import { Controller, Get, Query } from '@nestjs/common';
import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'; // swagger 接口文档import { PostParamsDto } from './dto/params-post.dto';
import { ResponsePostDto } from './dto/response-post.dto';
import { PostManageService } from './post-manage.service';@ApiTags('智能行政-岗位管理')
@Controller('post-manage')
export class PostManageController {constructor(private readonly postManageService: PostManageService) { }/*** @description: 查询岗位列表*/@Get()@ApiOkResponse({ type: ResponsePostDto })@ApiOperation({ summary: '获取岗位管理列表' })findAll(@Query() params: PostParamsDto) {return this.postManageService.findAll(params);}
}

常用 Swagger 装饰器

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

效果图

总结

在 Nest 中集成 Swagger 文档可以帮助开发者自动生成和维护 API 文档，Swagger 的集成提供了在线生成、‌自动生成、‌可操作数据库等优点，规范了 API 的标准化和一致性，后期还可以把 Swagger 文档导入到其他平台，例如 ApiFox

不足之处就是会增加开发者的工作量，每一个接口都需要保持注释和装饰器的准确性和完整性，仍然需要一定的维护工作。