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
}
配置后接口发起请求时即可对输入参数进行校验。
