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

Posted 2023-03-10

【中文标题】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"
          ]
        
      
    ]