什么是 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
安装依赖
bash 代码:pnpm add @nestjs/swagger swagger-ui-express
在 main.ts 文件中定义并初始化 SwaggerModule 类
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); // 构建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();
- 启动服务,访问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 中使用
在 DTO(响应数据传输对象) 文件中使用装饰器
ts 代码: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; }
在 Controller 控制器 中使用装饰器
ts 代码: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 中显示 |
效果图
![](https://cdn.baiwumm.com/images/202407/cz9r4j5zgochx1r1xc2g6og0yx5mlv8d.png)
总结
在 Nest 中集成 Swagger 文档可以帮助开发者自动生成和维护 API 文档,Swagger 的集成提供了在线生成、自动生成、可操作数据库等优点,规范了 API 的标准化和一致性,后期还可以把 Swagger 文档导入到其他平台,例如 ApiFox
不足之处就是会增加开发者的工作量,每一个接口都需要保持注释和装饰器的准确性和完整性,仍然需要一定的维护工作。