NestJS開發(fā)過程中使用 Swagger 文檔進行注釋和調(diào)試非常的方便，分享一下使用的心得:
NestJS 的安裝過程請自行搜索 NestJS 文檔
創(chuàng)建項目并進入到目錄
// 安裝過程假設用戶已經(jīng)全局安裝了 newtjs/cli
nest new thmall
cd thmall
- 安裝時系統(tǒng)會詢問用何種方式進行包管理，我們這里選擇
pnpm
項目創(chuàng)建界面
創(chuàng)建 RESTFUL 風格用戶接口
nest g resource user
- 創(chuàng)建完成后目錄
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
- 調(diào)整目錄結構根蟹，提高可讀性及方便日后維護,（這個步驟僅為個人習慣脓杉，非必要）
修改目錄后文件引用路徑會發(fā)生變化，使用
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
創(chuàng)建 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 中引用上述代碼的創(chuàng)建方法
// 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)
// 創(chuàng)建文檔
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 即可進行調(diào)試
點擊 try it out 即可進行調(diào)試
執(zhí)行后即可獲得接口運行結果散庶，非常方便. (紅框部分為服務器 返回邏輯蕉堰，是真實的運行結果)
紅框部分為服務器 返回邏輯，是真實的運行結果
使用 @nestjs/swagger 的裝飾器語法對CreateUserDto參數(shù)進行說明悲龟，當我們使用 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 實現(xiàn)數(shù)據(jù)校驗
安裝依賴:
pnpm i class-validator class-transformer
使用裝飾器語法對接口輸入數(shù)據(jù)進行驗證設置
// 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
}
配置后接口發(fā)起請求時即可對輸入?yún)?shù)進行校驗嘁灯。
