swagger

俗话说: 工欲善其事必先利其器, 最近正在学习 nest, 想自己编写后端接口, 如果要写接口的话，必然少不了文档,那么 swagger 就是一个比较好的 接口文档工具 (不知道还有其他比较好的工具没有) npm -swagger

swagger 在 nest 中的应用

1. 引入

    pnpm i --save @nestjs/swagger

2. 定义

在和 mian.ts 平级的文件中定义

固定写法，这个是利用了package.json 中的配置项来描述文档内容

package.json

{
  "name": "study-nest",
  "version": "0.0.2",
  "description": "学习nest",
  ...
 }

3. main.ts 中引入

import { generateDocument } from './doc';
async function bootstrap() {

  const app = await NestFactory.create(AppModule);
  // 创建文档
  generateDocument(app)
  // ....
   await app.listen(3000);
}

现在 swagger已经全局引入了，可以运行试试看了

启动 swagger

 http://localhost:3000/api/docs

那么配置出来的 swagger 长这样

4. 使用

ApiTags

在实际开发中，我们根据功能模块来创建接口，比如 用户模块,订单模块... 第一步就是要创建 模块名 比如在用户模块中，我们进入到 user.controller 中，添加 ApiTags

那么在 swagger 中会有这样的标识，表明下面的接口是属于 用户模块

🔥 ApiOperation

这个是对接口的具体描述，是用的最多的一个swagger装饰器

比如我想查找所有数据，我有可能这样写

一个简单的 get 请求，使用了 ParginationParamsDto定义参数

那么效果是这样的

非常的清晰，而且还可以定义 example ,还可以固定类型，真的大大提升了开发效率

ApiQuery / ApiParam

如果你不想使用 DTO 中的ApiOperation 定义入参类型,想随意一点

query 就是 user?id=xxxx这种形式，param 是 user/1的这种形式，和 前端中的路由差不多

可以通过 example 定义默认值，也可以设置required表明是否必传

ApiBody

上面的那两个是 get 请求参数的定义，这个 ApiBody 是 post 中的参数

那么效果是

ApiHeader

就是对请求头做定义，是否需要携带token，或者其他自定义请求头，一般我不咋用

  @ApiHeader({
      name: 'authoriation',
      required: true,
      description: '本次请求请带上token',
  })
  getUser(@Param('id') id: string, @Query('userName') userName: string) {
      return this.userService.getUser(id);
  }

🔥ApiResponse

如果你想让别人知道这个返回结果是样子，一方面可以直接执行，另一方面也可以自己定义返回结果

我只定义了 成功之后的返回结果，其他的状态可以继续添加 ApiResponse 装饰器

createUserDto结构

无需执行，swagger 的执行结果是这样，但是有可能和实际情况不对应

总结

一个好的文档是很重要的，它可以清晰的表明模块结构，准确的描述出接口的入参/传参，只有一个好的接口文档，前后端对接的时候才可以少一点疑惑，把精力集中处理其他更重要的事情上，虽然前期比较浪费时间，但是对于整体项目来说却是节约了时间，毕竟磨刀不误砍柴工