NestJS中如何使用Swagger生成在线接口文档

在前后端分离开发中，为了确保前端和后端的开发人员能够有效地协作，后端需要为前端提供接口文档。接口文档应包含请求类型、传参格式、响应格式等详细信息。在 NestJS 中，Swagger 可以将接口文档集成到项目中，并提供一个交互式界面，方便开发人员测试和调试 API 接口。本文将介绍如何使用 Swagger 在 NestJS 中生成 RESTful 风格接口的文档。

首先我们全局安装 Nest

css 复制代码

npm i -g @nestjs/cli

然后新建一个项目就叫 fs-admin,打开终端执行nest new xxx命令创建一个 nest 项目

arduino 复制代码

nest new admin_nest

选择 npm,等待一会就会发现我们的 nest_cli 项目创建完成了,它的目录结构如下

关于Nest相关介绍大家可以看这篇文章# 你有一份NestJS入门指南,请查收~

然后我们创建一个User模块

sql 复制代码

nest g res user

然后Nest就为我们自动创建了一个User模块

接下来看一下如何使用swagger,首先我们需要安装文档所用到的包@nestjs/swagger,swagger-ui-express

bash 复制代码

npm install @nestjs/swagger swagger-ui-express -S

在 main.ts 进行引入配置就可以使用了

js 复制代码

...
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const options = new DocumentBuilder()
    .setTitle('FS_ADMIN') // 标题
    .setDescription('后台管理系统接口文档') // 描述
    .setVersion('1.0') // 版本
    .build();

  const document = SwaggerModule.createDocument(app, options);
  //配置swgger地址
  SwaggerModule.setup('/fs_admin/api', app, document);
 ...
  await app.listen(3000);
}
bootstrap();

启动项目访问http://localhost:3000/fs_admin/api就可以看到 swagger 界面了

它会展示我们在controller中写的所有接口,但是我们看到上面所有接口都是在一起没有分类的,并且也没有请求和返回参数格式等,所以我们需要对其再进行一些配置。我们以 User 模块为例,来到user.controller.ts中,先引入ApiOperation和ApiTags给整个模块及单个接口添加一些信息

js 复制代码

...
import { ApiOperation, ApiTags } from '@nestjs/swagger';
@ApiTags('用户模块')
@Controller('user')
export class UserController {
  constructor(
    private readonly userService: UserService,
  ) {}
  @ApiOperation({
    summary: '添加用户', // 接口描述信息
  })
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }
  ...
  }

刷新页面再看一下变化

此时我们看到我们对 User 模块接口进行了分类,并且给接口做了说明。

接下来我们再配置一下接口入参信息以及接口返回数据信息,一般在我们开发过程中,前端传来的数据信息会放在DTO(Data Transfer Object)中,而返回给前端的数据则定义在VO(Value Object)中。可以看到上面示例接口用的是CreateUserDto,所以我们来到create-user.dto.ts中定义前端传来的参数,再调用 swagger 中的 ApiProperty 定义文档上展示的传参内容

js 复制代码

import { ApiProperty } from "@nestjs/swagger";
export class CreateUserDto {
  @ApiProperty({
    example: "admin",
    description: "用户名",
  })
  username: string;
  @ApiProperty({
    example: "123456",
    description: "密码",
  })
  password: string;
}

可以看到这时候示例值已经有了,接下来我们在 user 目录下新建vo/create-user.vo.ts用来描述这个接口的返回值

js 复制代码

import { ApiProperty } from "@nestjs/swagger";

export class CreateUserVo {
  @ApiProperty({ example: 200 })
  code: number;
  @ApiProperty({ example: "xxx" })
  data: string;
  @ApiProperty({ example: "请求成功" })
  describe: string;
}

然后在user.controller.ts导入装饰器ApiOkResponse修饰一下就行了

js 复制代码

import { ApiOperation, ApiTags, ApiOkResponse } from '@nestjs/swagger';
@ApiTags('用户模块')
@Controller('user')
export class UserController {
  constructor(
    private readonly userService: UserService,
    private cacheService: CacheService,
  ) {}
  @ApiOperation({
    summary: '添加用户', // 接口描述信息
  })
  @ApiOkResponse({
    description: '返回示例',
    type: CreateUserVo,
  })
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }
  ...
  }

刷新页面你就会看到有了返回示例

不仅如此,你还可以点击旁边的tryout按钮对接口进行调试,是不是非常方便!

因为有些接口需要登录才能访问,因此需要在 swagger 中配置 token。

其实很简单,只需要在 main.ts 再加个 addBearerAuth()函数即可

js 复制代码

const options = new DocumentBuilder()
  .setTitle("FS_ADMIN") // 标题
  .setDescription("后台管理系统接口文档") // 描述
  .setVersion("1.0") // 版本
  .addBearerAuth()
  .build();

然后在需要认证的接口加上@ApiBearerAuth()装饰器,比如还是这个/user接口

js 复制代码

@ApiBearerAuth()
  @ApiOperation({
    summary: '添加用户', // 接口描述信息
  })
  @ApiOkResponse({
    description: '返回示例',
    type: CreateUserVo,
  })
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }

这时候就会发现这个接口旁边多了一个锁,点击它,假如需要登录,我们可以将调用登录接口取得的 token 输入进去即可调用加了权限的接口了

ok,到这里我们就已经学会了 Swagger 的基本用法,后续写接口的时候就可以进行使用了,这样的话我们就可以不用再单独去写接口文档了,是不是十分的方便!