什么是 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
不足之处就是会增加开发者的工作量，每一个接口都需要保持注释和装饰器的准确性和完整性，仍然需要一定的维护工作。
评论