Swagger

Swagger 是一个能够生成、描述、调用和可视化的 RESTful 风格的 Web 服务。主要是对 REST API 接口自动生成接口说明文档。生成的接口文档也是直接在线测试。即在可视化的Web 界面上直接输入参数对应的值就可以在线测试接口。

Nest 框架也提供了一个专门用于支持 Swagger 规范的模块。

开始使用

安装 swagger 包

默认底层框架 express

 pnpm add --save @nestjs/swagger swagger-ui-express -w

如果是 fastify 框架

pnpm  --save @nestjs/swagger fastify-swagger -w

创建 swagger 实例

在 Nest 项目的 main.ts 文件中，使用 SwaggerModule 类初始化 Swagger

import { NestFactory } from '@nestjs/core';
import { ValidationPipe, Logger } from '@nestjs/common';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new Logger(), // 配置日志
  });

  // 全局校验
  app.useGlobalPipes(new ValidationPipe());

  //注入文档
  const options = new DocumentBuilder()
    .setTitle('Api example')
    .setDescription('The API description')
    .setVersion('1.0')
    .addTag('Api/V1')
    .build();

  const swaggerDocument = SwaggerModule.createDocument(app, options);

  SwaggerModule.setup('api', app, swaggerDocument); // 这里第一个参数配置路由地址

  // 监听端口
  await app.listen(8888);
}

bootstrap();

DocumentBuilder : 先new 一个 DocumentBuilder 实例，主要是为构建符合 OpenApi规范的基础文档，从以上Demo中可以看到可以对 Swagger 文档设置标题、描述、版本号、tag的相关属性。
createDocument()：用于创建文档。该方法主要接收两个参数：一个是 app 应用程序实例，一个是 Swagger 选项对象。

创建完文件之后，即可调用 setup 方法。

代码简洁抽象化

在 src 下单独配置 swagger 配置文件

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import * as packageConfig from '../package.json'; // 这里需要配置 tsconfig.json -> "resolveJsonModule": true 才可以引入 json 文件

export const generateSwaggerDocument = (app) => {
  const { name, version, description } = packageConfig;

  //注入文档
  const options = new DocumentBuilder()
    .setTitle(name)
    .setDescription(description)
    .setVersion(version)
    .addTag('Api/V1')
    .build();

  const swaggerDocument = SwaggerModule.createDocument(app, options);

  SwaggerModule.setup('api', app, swaggerDocument);
};

使用 swagger 配置

import { NestFactory } from '@nestjs/core';
import { ValidationPipe, Logger } from '@nestjs/common';
import { AppModule } from './app.module';
import { generateSwaggerDocument } from './swaggerDoc';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new Logger(), // 配置日志
  });

  // 全局校验
  app.useGlobalPipes(new ValidationPipe());

  // 创建 swagger 文档
  generateSwaggerDocument(app);

  // 监听端口
  await app.listen(8888);
}

bootstrap();

配置完之后，就可以在运行项目，通过访问 http://localhost:8888/api，就可以打开 Swagger 的可视化界面，其中就会展示所有的接口列表。

调用文档描述功能

ApiTags 可以进行接口的分组

//sensitive.controller.ts
import { Controller, Get, Query } from '@nestjs/common';
import { SensitiveService } from './sensitive.service';
import { SensitiveType } from './constants';
import { ApiTags } from '@nestjs/swagger';

@Controller('sensitive')
@ApiTags('敏感数据')
export class SensitiveController {
  constructor(private readonly sensitiveService: SensitiveService) {}

  // http://localhost:8888/sensitive/get-by-type?type=set
  @Get('/get-by-type')
  getSensitive(@Query('type') type: SensitiveType) {
    return this.sensitiveService.getSensitive(type);
  }
}

等等还有很多种类型的文档预注释方法就不一一列举了，直接查看官网文档即可

Nest.js 学习笔记（五）- 集成 Swagger 测试文档