在NestJs上配置Swagger

在NestJs上配置Swagger

关于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);

页面后效果启动如下:

在NestJs上配置Swagger

配置模块

但此时,我们的项目只是配置了swagger,还没有设置具体的模块,所以我们需要在具体的controller中,添加@ApiTags()标签。

用法如下:

@ApiTags('Health Check')
@Controller()
export class HealthController {
  constructor(private readonly appService: HealthService) {}
  @Get('_health')
  getOk(): string {
    return this.appService.getOk();
  }
}

效果如下:

在NestJs上配置Swagger

配置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();
  }
}

此时页面效果如下
在NestJs上配置Swagger

在NestJs上配置Swagger

这样子,我们一看到有带锁的模块,就知道是需要token的模块了。

公众号文章链接~求关注

个人博客~求关注,多谢晒

原文链接:https://juejin.cn/post/7346501899660984383 作者:做全栈开发的前端开发搬砖林小白

(0)
上一篇 2024年3月16日 上午10:15
下一篇 2024年3月16日 上午10:27

相关推荐

发表回复

登录后才能评论