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

Question

我正在开发一个使用 NestJS 框架的 Node.js 服务器。我想使用NestJS 的 swagger 集成为应用程序自动构建 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 中的端点无法显示具有任何参数的端点。使用 s 为 NestJS 控制器编写 GET 端点@Param以便 swagger 正确生成文档的正确方法是什么？

Answer 1

看来我的自定义装饰器@RouteLogger()在某种程度上与招摇的文档生成发生了冲突。

当我将该装饰器移动到 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
  ) { }

Answer 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"
          ]
        }
      }
    ]
  }
}