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
- 安装依赖
pnpm add @nestjs/swagger swagger-ui-express
- 在
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();
- 启动服务，访问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(响应数据传输对象)文件中使用装饰器
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 控制器中使用装饰器
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
不足之处就是会增加开发者的工作量，每一个接口都需要保持注释和装饰器的准确性和完整性，仍然需要一定的维护工作。
原文地址：https://blog.csdn.net/qq_36117388/article/details/140517419
免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！