使用Swagger构建Node.js API文档与Mock Server

Posted 2023-03-30

参考技术A Swagger是一个编写API文档的套件组合，而不是一个单一的工具。具体可以在官网看到。
Swagger可以实现很多功能，这里只说最基础、常用的：
1. API文档撰写 —— Swagger Editor
2. API文档的显示 —— Swagger UI
3. 生成Mock服务 —— Swagger Editor

目前我们很多项目采用的都是新建一个markdown，写文档，每次改接口，就打开旧的markdown=>编辑=>保存=>复制并发布到项目wiki。

Swagger Editor可以解决1、3、4，不止具有语法提示、语法检测，还支持定义对象，一处定义多处使用，减少重复编写，写好后可以一键生成Mock Server，而且支持生成多种语言的：

Swagger UI则是一套Web展示框架，把你用Swagger Editor写出来的东西，漂亮地展示出来：

首先， 安装Editor ，安装方式多种可选。
最简单的就是使用Docker，只需要pull镜像，run镜像，就可以使用了，完全不用任何多余步骤。
不推荐在线Editor，亲测特别慢，毕竟是国外的服务器。

此处有两个概念，不要混淆： 语法（YAML或者JSON 和 规范（OpenAPI） 。
OpenAPI规范就是我们期望的一套API撰写的完整规范，包括如何说明参数、请求方法、响应码、响应体等。
YAML和JSON是Swagger Editor能够读懂的语法。
用YAML或者JSON写出符合OpenAPI规范的文档 = 用javascript写出符合Restful规范的接口

建议打开 Swagger的在线Editor ，对照着示例，边看边敲边学。

我们希望文档能跟在项目中，项目部署到服务器后，可以在项目服务器浏览到文档，而不用单独管理文档。

非常简单，在Editor中选择 Generate Server ，选择你想要的语言就可以：

我们之前使用Swagger Editor编辑文档，也可以借助框架，从注释生成文档，而不使用Editor。

使用 swagger-tools 的 swagger-router中间件 即可实现，具体没有测试，待大家发现。

NestJS swagger 生成的文档不显示参数信息

【中文标题】NestJS swagger 生成的文档不显示参数信息

【英文标题】：NestJS swagger generated docs do not show param information

【发布时间】：2021-04-19 01:05:58

【问题描述】：

我正在开发一个使用 NestJS 框架的 node.js 服务器。我想使用 NestJS's swagger integration 为应用程序自动构建 API 文档。

为我使用@Body() 方法进行控制器数据交换的控制器方法正确生成的文档。对于使用 @Param() 方法的控制器方法，它无法正常工作。无法生成正确文档的示例控制器：

  @Get('/:identifier')
  @RouteLogger()
  @ApiParam(name: 'identifier', required: true, description: 'either an integer for the project id or a string for the project name', schema:  oneOf: [type: 'string', type: 'integer'])
  async getProject(
    @Param('identifier')
    identifier: string | number,
    @Res() res: Response
  )  

这会在 swagger UI 中生成以下内容：

您可以看到，swagger UI 中的端点无法显示具有任何参数的端点。使用@Params 为nestJS 控制器编写GET 端点以便swagger 正确生成文档的正确方法是什么？

【问题讨论】：

您好，我遇到了同样的问题。停止服务器，删除 dist 文件夹，重新开始，这对我有帮助。

【参考方案1】：

我的自定义装饰器 @RouteLogger() 似乎在某种程度上与 swagger doc 生成冲突。

将装饰器移到 API @ApiParam() 装饰器下方后，文档生成正确：

  @Get('/:identifier'
  @ApiParam(name: 'identifier', required: true, description: 'either an integer for the project id or a string for the project name', schema:  oneOf: [type: 'string', type: 'integer'])
  @RouteLogger()
  async getProject(
    @Param('identifier')
    identifier: string | number,
    @Res() res: Response
  )  

【讨论】：

我遇到了同样的问题，但没有出现。将其移到@Get 下即可解决。

【参考方案2】：

很高兴您已经找到了解决方案！

您还可以使用 OpenAPI 的 CLI 插件自动获取这些参数（不使用装饰器），如文档中所述：https://docs.nestjs.com/openapi/cli-plugin。

为此，您只需更改nest-cli.json，包括compilerOptions，如下所示：

  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": 
    "plugins": ["@nestjs/swagger"]
  

或者像这样，如果您需要将选项传递给插件：

  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": 
    "plugins": [
      
        "name": "@nestjs/swagger/plugin",
        "options": 
          "dtoFileNameSuffix": [
            ".entity.ts",
            ".dto.ts"
          ],
          "controllerFileNameSuffix": [
            ".controller.ts"
          ]
        
      
    ]