在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);

页面后效果启动如下：

配置模块

但此时，我们的项目只是配置了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的模块了。

公众号文章链接~求关注

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