Nest 使用 swagger 生成文档

api 文档

当写好接口之后，要把接口信息同步给前端或者其他同事。这时候就会用到 api 文档，当然 api 文档你可以用任何方式记录，甚至是 word 文档。但是这有点太不程序猿了。所以一般能自动的绝不手动，把项目中接入 swagger 来自动生成 api 文档。

安装

先安装 swagger 相关的依赖包

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

配置

然后需要在 main.ts 中进行相关的设置配置

...
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  ...
  // 设置swagger文档
  const config = new DocumentBuilder()
    .setTitle('管理后台')
    .setDescription('管理后台接口文档')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docsapi', app, document);

   await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

接口标签

但是这样虽然能显示出接口文档，但是并没分类，看起来不够清晰，所以需要通过加接口标签来分类。

可以根据 Colltroller 来进行分类，使用@ApiTags 装饰器就行了

...
import { ApiTags } from '@nestjs/swagger';
import { Body, Controller, Delete, Get, Param, Post, Put, Query } from '@nestjs/common';

@ApiTags("文章")
@Controller('post')
export class PostsController {...}

接口描述

如上虽然对接口做了分类，但是每一个接口是做什么的并没有一个简单的说明，为了看文档更加方便，优化一下加一些文字描述说明

给每一个接口加上说明之后，能够直观的理解当前接口的作用什么，可以通过@ApiOperation 装饰器来加上描述

//  posts.controller.ts
...
import { ApiTags,ApiOperation } from '@nestjs/swagger';
export class PostsController {

  @ApiOperation({ summary: '创建文章' })
  @Post()
  async create(@Body() post) {....}

  @ApiOperation({ summary: '获取文章列表' })
  @Get()
  async findAll(@Query() query): Promise<PostsRo> {...}
  ....
}

访问

在 APIFOX 里面导入:

http://localhost:3000/docsapi-json

访问的话

http://localhost:3000/docsapi

小结

简单整理了 api 接口开发需要的知识点