关于Swagger
Swaager是生成开发API文档的一大利器,当我们在给别人做KT的时候,一个Swagger文档丢给人家,真的是你好我也好。
在日常开发中,前端看Swagger文档也可以避免很多沟通上的非必要问题。
Swagger的版本
NestJS有两种开箱即用的HTTP模式,最为常用的是Express的,所以我们在NestJS的基础上开发Swaager的时候,可以适当参考Express的文档,但由于NestJS是完全的使用TypeScript进行开发,所以也只能起到借鉴的作用。
NestJS作为流行的NodeJS框架,对Swagger的封装也已经很完善了,所以我们只需要安装@nestjs/swagger 包即可。
需要注意的是,本次示例中使用的版本是
“^7.1.14"
由于7.x的版本使用的是Swagger3.x,所以本篇的语法是使用的v3
Migration from v3
NestJs使用Swagger
由于Swaager是属于整个项目的,所以我们会在项目的main.ts文件中配置项目的Swagger
首先需要做的是在包中引入我们的两个对象,用于构建swaager的document以及module
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
接着构建出一个swaager的document对象
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('API')
.setDescription("project description")
.setVersion(process.env.npm_package_version)
.addServer(`http://localhost:${environmentConfig.server.node_port}/`, 'Local environment')
.build();
其中,title跟descrption指的是标题以及描述,具体待会在UI中体现出来。最主要的是我们的addServer方法,指的是我们的服务的地址,一般来说都会是在localhost:3000/swaager
构建完对象结构后,需要调用下面的代码去生成一个document
const document = SwaggerModule.createDocument(app, config);
最后再将整个页面设置进去,即
SwaggerModule.setup('swagger', app, document);
页面后效果启动如下:
配置模块
但此时,我们的项目只是配置了swagger,还没有设置具体的模块,所以我们需要在具体的controller中,添加@ApiTags()标签。
用法如下:
@ApiTags('Health Check')
@Controller()
export class HealthController {
constructor(private readonly appService: HealthService) {}
@Get('_health')
getOk(): string {
return this.appService.getOk();
}
}
效果如下:
配置token
对于服务是否健康的时候,我们会设置一个_health的接口,方便我们的服务器进行检测,但对于其他的服务,出于项目的安全问题,我们需要设置一个token来进行校验,同样的,我们的Swagger也需要在header中放置一个token,毕竟我们不可能在项目中对swagger开一个后门的~
您可以使用类的addBearerAuth()方法启用承载授权DocumentBuilder。然后限制所选路线或整个控制器,使用@ApiBearerAuth()装饰器。
具体用法如下:
首先,在main.ts中的config中,我们需要添加”addBearerAuth“
const config = new DocumentBuilder()
.setTitle(' API')
.setDescription('description')
.setVersion(process.env.npm_package_version)
.addBearerAuth()
.addServer(`http://localhost:${environmentConfig.server.node_port}/`, 'Local environment')
.build();
接着,在需要我们设置token校验的controller中添加
@ApiBearerAuth()
@ApiTags('Health Check')
@ApiBearerAuth()
@Controller()
export class HealthController {
constructor(private readonly appService: HealthService) {}
@Get('_health')
getOk(): string {
return this.appService.getOk();
}
}
此时页面效果如下
这样子,我们一看到有带锁的模块,就知道是需要token的模块了。
个人博客~求关注,多谢晒
原文链接:https://juejin.cn/post/7346501899660984383 作者:做全栈开发的前端开发搬砖林小白