NestJS 实战(1) 集成 Swagger 文档直接调试接口

NestJS开发过程中使用 Swagger 文档进行注释和调试非常的方便，分享一下使用的心得:

NestJS 的安装过程请自行搜索 NestJS 文档

创建项目并进入到目录

// 安装过程假设用户已经全局安装了 newtjs/cli
nest new thmall
cd thmall

• 安装时系统会询问用何种方式进行包管理，我们这里选择 pnpm
  项目创建界面

创建 RESTFUL 风格用户接口

nest g resource user

• 创建完成后目录

user
├── dto
│   ├── create-user.dto.ts
│   └── update-user.dto.ts
├── entities
│   └── user.entity.ts
├── user.controller.spec.ts
├── user.controller.ts
├── user.module.ts
├── user.service.spec.ts
└── user.service.ts

• 调整目录结构，提高可读性及方便日后维护,（这个步骤仅为个人习惯，非必要）

修改目录后文件引用路径会发生变化，使用 vscode 编辑器会自动修改，若报错需要手动处理一下

user
├── controllers
│   └── user.controller.ts
├── dto
│   ├── create-user.dto.ts
│   └── update-user.dto.ts
├── entities
│   └── user.entity.ts
├── services
│   └── user.service.ts
└── user.module.ts

创建 Swagger 文档

安装依赖

pnpm i @nestjs/swagger

在 src 目录下添加 doc.ts 文件，配置 swagger 文档

// src/doc.ts
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
import * as packageConfig from '../package.json'

export const generateDocument = (app) => {
  const options = new DocumentBuilder()
    .setTitle(packageConfig.name)
    .setDescription(packageConfig.description)
    .setVersion(packageConfig.version)
    .addBearerAuth() // 允许tonken鉴权
    .build()

  const document = SwaggerModule.createDocument(app, options)
  SwaggerModule.setup('/api/doc', app, document)
}

引用 json 文件需要先配置 tsconfig:

// src/tsconfig.json

"resolveJsonModule": true,

在 main.ts 中引用上述代码的创建方法

// src/main.ts
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'
import { generateDocument } from './doc'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)

  // 创建文档
  generateDocument(app)
  await app.listen(3000)
}
bootstrap()

使用代码 pnpm start:dev 运行服务端，成功后在浏览器访问文档地址 (http://localhost:3000/api/doc/)[http://localhost:3000/api/doc/]即可访问文档

swagger文档页面

用 @nestjs/swagger 的装饰器语法进行 swagger 文档注释

// src/user/controllers/user.controller.ts
... 
@ApiTags('用户')
@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @ApiOperation({
    summary: '新增用户',
  })
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto)
  }
...
}

添加文档注释后的页面

添加文档注释后的页面

点击 try it out 即可进行调试

点击 try it out 即可进行调试

执行后即可获得接口运行结果，非常方便. (红框部分为服务器 返回逻辑，是真实的运行结果)

红框部分为服务器 返回逻辑，是真实的运行结果

使用 @nestjs/swagger 的装饰器语法对CreateUserDto参数进行说明，当我们使用 example 属性时就可以在 swagger 文档上设置默认测试的值

// src/user/dto/create-user.dto.ts
import { ApiProperty } from '@nestjs/swagger'

export class CreateUserDto {
  @ApiProperty({ example: '18888888888' })
  readonly phoneNumber: string

  @ApiProperty({ example: 'Nick' })
  name: string

  @ApiProperty({ example: '123456' })
  password: string

  @ApiProperty({ example: 'qqqa@qq.com' })
  email: string
}

可以得到结果如下

设置 example 结果

使用 Pipe 实现数据校验

安装依赖:

pnpm i class-validator class-transformer

使用装饰器语法对接口输入数据进行验证设置

// src/user/dto/create-user.dto.ts
import { ApiProperty } from '@nestjs/swagger'

import { IsNotEmpty, Matches } from 'class-validator'

export class CreateUserDto {
  @ApiProperty({ example: '18888888888' })
  @IsNotEmpty({ message: '请输入手机号' })
  @Matches(/^1\d{10}$/g, { message: '请输入手机号' })
  readonly phoneNumber: string

  @ApiProperty({ example: 'Nick' })
  @IsNotEmpty()
  name: string

  @ApiProperty({ example: '123456' })
  @IsNotEmpty()
  password: string

  @ApiProperty({ example: 'qqqa@qq.com' })
  @IsNotEmpty()
  email: string
}

配置后接口发起请求时即可对输入参数进行校验。