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

Question

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

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

@Param()

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

您可以看到 swagger UI 中的端点无法显示具有任何参数的端点。为带有 @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 ) { } 的 nestJS 控制器编写 GET 端点以便 swagger 正确生成文档的正确方法是什么？

Answer 1

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

将该装饰器移至 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"
          ]
        }
      }
    ]
  }
}