Nest.js OpenApi 规范实现

Jaxson Wang 编程技术 阅读量

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

喵~
Jaxson Wang
永远年轻,永远热泪盈眶!
Nest.js 散列和加密
Nest.js 散列和加密

散列是给键值经过数学算法转换另外一个键值,在转换过程中是利用哈希函数生成,输出的内容无法还原,这边主要用于密码存储在数据需要进行散列处理。加密是对信息编码,将原始信息转换成密文,一般用于客户端向服务器发送密码等敏感信息,发送之前对此信息加密,然后在服务器再进行解密。

2 分钟阅读
Nest.js 授权验证
Nest.js 授权验证

系统授权指的是登录用户执行操作过程,比如管理员可以对系统进行用户操作、网站帖子管理操作,非管理员可以进行授权阅读帖子等操作,所以实现需要对系统的授权需要身份验证机制,下面来实现最基本的基于角色的访问控制系统。

6 分钟阅读