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

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