大学网站模板下载,高要区公路建设规划局网站,免费建外贸网站,重庆好的推广网站什么是swagger Swagger 是一个规范和完整的框架#xff0c;用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是#xff1a; 1. 使得前后端分离开发更加方便#xff0c;有利于团队协作 2. 接口的文档在线自动生成#xf…什么是swagger Swagger 是一个规范和完整的框架用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是 1. 使得前后端分离开发更加方便有利于团队协作 2. 接口的文档在线自动生成降低后端开发人员编写接口文档的负担 3. 功能测试
安装配置
安装nestjs/swagger然后在main.ts进行引入配置
import { DocumentBuilder, SwaggerModule } from nestjs/swaggerconst 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引入ApiOperationApiTags
import { Body, Controller, Post, Req } from nestjs/common
import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from nestjs/swaggerimport { UserEntity } from ./entities/user.entity
import { UserService } from ./user.serviceimport { LoginUser } from ./dto/login-user.dto
import { CreateUserDto } from ./dto/create-user.dto
import { CreateTokenDto } from ./dto/create-token.dtoApiTags(登录注册)
Controller()
export class BaseController {constructor(private readonly userService: UserService) {}Post(register)ApiOperation({ summary: 用户注册 })async create(Body() user: CreateUserDto): PromiseRegisterResponse {return await this.userService.create(user)}Post(login)ApiOperation({ summary: 登录 })async login(Body() dto: LoginUser): PromiseLoginResponse {return await this.userService.login(dto.account, dto.password)}Post(/update/token)ApiOperation({ summary: 刷新token })async updateToken(Req() req:any): PromiseUpdateTokenResponse {return await this.userService.updateToken(req.user.id)}
}
刷新文档页面就可以看到我们加的分组和接口描述信息了 接下来我们再配置一下入参信息,入参信息需要在login-user.dto.ts引入ApiProperty(定义 post 请求参数)进行配置
import { ApiProperty } from nestjs/swaggerexport class LoginUser {ApiProperty({ description: 账号,example: admin })readonly account: stringApiProperty({ 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.dtoApiTags(登录验证模块)
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,就会看到我们定义的响应数据了
