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/]
即可访问文档
![](https://img.haomeiwen.com/i126473/fcd1cc400b368f22.png)
用 @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)
}
...
}
添加文档注释后的页面
![](https://img.haomeiwen.com/i126473/1c236f363fbb3892.png)
点击 try it out 即可进行调试
![](https://img.haomeiwen.com/i126473/5ea207dcf9cc8dbf.png)
执行后即可获得接口运行结果,非常方便. (红框部分为服务器 返回逻辑,是真实的运行结果)
![](https://img.haomeiwen.com/i126473/18a0876925e2d11e.png)
使用 @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
}
可以得到结果如下
![](https://img.haomeiwen.com/i126473/c0d792bdb6c1b657.png)
使用 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
}
配置后接口发起请求时即可对输入参数进行校验。
网友评论