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

【问题标题】：NestJS swagger generated docs do not show param informationNestJS swagger 生成的文档不显示参数信息
【发布时间】：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 文件夹，重新开始，这对我有帮助。

标签： javascript typescript swagger nestjs openapi

【解决方案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"
          ]
        }
      }
    ]
  }
}

【讨论】：