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. 安装依赖

   bash 代码:

   pnpm add @nestjs/swagger swagger-ui-express

2. 在 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();

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

DocumentBuilder 属性

在 Nest 中使用

1. 在 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;
    }

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

效果图

总结

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

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