Nest.js权限管理系统开发（四）Swagger API接入

什么是swagger

        Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(<https://swagger.io/>)。 它的主要作用是：

        1. 使得前后端分离开发更加方便，有利于团队协作

        2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

        3. 功能测试 

安装配置

安装@nestjs/swagger，然后在main.ts进行引入配置

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'const swaggerOptions = new DocumentBuilder().setTitle('Nest-Admin App').setDescription('Nest-Admin App 接口文档').setVersion('2.0.0').addBearerAuth().build()const document = SwaggerModule.createDocument(app, swaggerOptions)// 项目依赖当前文档功能，最好不要改变当前地址// 生产环境使用 nginx 可以将当前文档地址 屏蔽外部访问SwaggerModule.setup("api/docs", app, document, {swaggerOptions: {persistAuthorization: true,},customSiteTitle: 'Nest-Admin API Docs',})

启动项目访问http://localhost:3000/api/docs就可以看到 swagger 界面了。

接口配置

我们看到上面所有接口都是混在一起、没有分类的，并且也没有请求和返回参数格式。所以我们需要对其再进行一些配置，这里就以/login接口为例。

考虑到注册登录都是用户相关的功能，我们使用nest g resource users新建一个user模块。在user模块下创建一个base.controller.ts，引入ApiOperation，ApiTags：

import { Body, Controller, Post, Req } from '@nestjs/common'
import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'import { UserEntity } from './entities/user.entity'
import { UserService } from './user.service'import { LoginUser } from './dto/login-user.dto'
import { CreateUserDto } from './dto/create-user.dto'
import { CreateTokenDto } from './dto/create-token.dto'@ApiTags('登录注册')
@Controller()
export class BaseController {constructor(private readonly userService: UserService) {}@Post('register')@ApiOperation({ summary: '用户注册' })async create(@Body() user: CreateUserDto): Promise<RegisterResponse> {return await this.userService.create(user)}@Post('login')@ApiOperation({ summary: '登录' })async login(@Body() dto: LoginUser): Promise<LoginResponse> {return await this.userService.login(dto.account, dto.password)}@Post('/update/token')@ApiOperation({ summary: '刷新token' })async updateToken(@Req() req:any): Promise<UpdateTokenResponse> {return await this.userService.updateToken(req.user.id)}
}

刷新文档页面就可以看到我们加的分组和接口描述信息了：

接下来我们再配置一下入参信息,入参信息需要在login-user.dto.ts引入ApiProperty(定义 post 请求参数)进行配置：

import { ApiProperty } from '@nestjs/swagger'export class LoginUser {@ApiProperty({ description: '账号',example: 'admin' })readonly account: string@ApiProperty({ description: '密码',example: 'admin' })readonly password: string
}

然后再看文档页面：

同时可以点击 try it out 按钮进行接口的调用

有了请求参数格式,还需要提供返回数据格式给前端,返回参数的定义可以用ApiOkResponse进行配置,如

 @ApiOkResponse({ description: '登录成功返回', type: LoginResponse })

其中LoginResponse需要我们根据具体格式自定义,这里新建一个文件定义auth模块的接口返回格式(vo/auth.vo.ts)

import { ApiProperty } from '@nestjs/swagger';export class LoginResponse {@ApiProperty({ example: 200 })code: number;@ApiProperty({ example: 'eyJhbGciOiJ...' })data: string;@ApiProperty({ example: '请求成功' })msg: string;
}

然后在base.controller.ts进行响应数据的配置

...
import { ApiOperation, ApiTags, ApiOkResponse } from '@nestjs/swagger';
import { LoginResponse } from './vo/auth.vo';
import { LoginUser } from './dto/login-user.dto'@ApiTags('登录验证模块')
@Controller()
export class BaseController {constructor(private readonly userService: UserService) {}@ApiOperation({summary: '登录接口', // 接口描述信息})@ApiOkResponse({ description: '登录成功返回', type: LoginResponse })@Post('login')login(@Body() loginUser: LoginUser) {return this.userService.login(loginUser);}}

刷新swagger,就会看到我们定义的响应数据了