0x0 前言
OpenApi 规范是定义与 RESTful Api
的语言无关的标准接口,使用它不需要花大量的时间来编写接口文档。Nest
提供一个模块,使系统支持此规范。
需要安装依赖如下:
yarn add @nestjs/swagger swagger-ui-express
0x1 初始化
在 main.ts
启用模块,使用 SwaggerModule
类来初始化 Swagger
:
import { NestFactory } from '@nestjs/core'
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'
import { AppModule } from './app.module'
async function bootstrap() {
const app = await NestFactory.create(AppModule)
const config = new DocumentBuilder()
.setTitle('Vue Admin Plus 管理系统接口文档')
.setDescription('这是一份关于 Vue Admin Plus 管理系统的接口文档')
.setVersion('1.0.0')
.build()
const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('api', app, document)
await app.listen(3000)
}
bootstrap().then()
然后可以访问 localhost:3000/api
即可看到 Swagger UI
文档。
0x2 类型和参数
SwaggerModule
搜索项目中所有可用的 @Body()
, @Query()
和 @Param()
装饰器来生成 Api
文档,同样可以利用反射来创建模型定义:
@Post()
create(@Body() createUserDto: CreateUserDto): Promise<UserEntity> {
return this.userService.create(createUserDto)
}
上述代码会在 Swagger UI
生成模型,不过属性显示为空,需要添加注解才能支持:
import { ApiProperty } from '@nestjs/swagger'
import { IsNotEmpty } from 'class-validator'
export class CreateUserDto {
@ApiProperty({
type: String,
description: '用户账号'
})
@IsNotEmpty()
readonly username: string
@ApiProperty({
type: String,
description: '用户密码'
})
@IsNotEmpty()
readonly password: string
@ApiProperty({
type: String,
description: '用户邮箱'
})
@IsNotEmpty()
readonly email: string
@ApiProperty({
type: String,
description: '用户昵称'
})
@IsNotEmpty()
readonly nickname: string
}
0x3 备注信息
默认文档渲染比较杂乱,可以利用 @ApiTags()
装饰器可以添加标签进行归纳:
@ApiTags('user')
@Controller('user')
export class UserController {}
如果需要自定义标头信息,可以用使用 @ApiHeader()
装饰器进行定义:
@ApiHeader({
name: 'X-MyHeader',
description: 'Custom header',
})
@Controller('user')
export class UserController {}
如果需要自定义响应信息可以使用 @ApiResponse()
装饰器:
@Post()
@ApiResponse({ status: 201, description: 'The record has been successfully created.'})
@ApiResponse({ status: 403, description: 'Forbidden.'})
async create(@Body() createUserDto: CreateUserDto) {
this.userService.create(createCatDto)
}
0x4 安全机制
对于特定的安全机制可以用 @ApiSecurity()
装饰器定义:
@ApiSecurity('basic')
@Controller('cats')
export class CatsController {}
然后在 main.ts
初始化的时候添加属性:
const options = new DocumentBuilder().addSecurity('basic', {
type: 'http',
scheme: 'basic'
})
0x5 身份认证
对于身份验证需要 @ApiBasicAuth()
装饰器:
@ApiBasicAuth()
@Controller('cats')
export class CatsController {}
初始化添加属性:
const options = new DocumentBuilder().addBasicAuth()
0x6 承载认证
对于承载认证需要 @ApiBearerAuth()
装饰器:
@ApiBearerAuth()
@Controller('cats')
export class CatsController {}
初始化添加属性:
const options = new DocumentBuilder().addBearerAuth()
如果需要验证需要承载认证的接口,在
Swagger UI
的接口最右边小锁的图标点开,登录获取的Token
字符串复制塞进去即可。