Nest.js OpenApi 规范实现

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 文档。

iShot2021-02-22

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 字符串复制塞进去即可。

0x7 参考

Nest OpenApi Docs