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 属性

在 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 装饰器

效果图

总结

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

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