NestJS API的Swagger UI中GET接口路径参数缺失问题排查求助

使用Swagger测试查看API详情时，发现POST接口参数显示正常，但GET接口的两个路径参数（entityType、entityId）在UI中缺失。相关代码示例如下：

@Get(':entityType/:entityId')
@Permissions(ApplicationPermissions.hasApplicationAccess)
async find(
  @Param('entityType', new ParseEntitTypePipe()) entityType: EntityTypes,
  @Param('entityId', ParseIntPipe) entityId: number
) {
  this.logger.verbose(
    `[GET] Find documents for entity type ${entityType} with id ${entityId}`,
    'DocumentsController'
  );
  return await this.documentsService.find(entityType, entityId);
}

@Post(':entityType/:entityId')
@Permissions(ApplicationPermissions.hasApplicationAccess)
@UseInterceptors(
  AnyFilesInterceptor({
    storage: diskStorage({
      destination: storageLocation,
      filename: storageFilename
    })
  })
)

排查方向： #

• 显式添加Swagger参数注解：POST接口因文件拦截器可能自动触发参数识别，而GET接口需显式声明@ApiParam装饰器。比如给每个路径参数添加：

  @ApiParam({ name: 'entityType', description: '实体类型', enum: EntityTypes })
  @ApiParam({ name: 'entityId', description: '实体ID', type: Number })
  

  确保Swagger能识别参数元数据。

• 排查参数校验管道问题：检查ParseEntitTypePipe（注意拼写是否应为ParseEntityTypePipe）是否正确实现PipeTransform接口，是否干扰了Swagger的反射元数据。可暂时移除该管道，测试参数是否正常显示，定位是否为管道导致的元数据丢失。

• 检查Swagger版本兼容性：不同版本的@nestjs/swagger可能存在路径参数解析bug，查看官方文档或GitHub issues确认当前版本是否有相关问题，尝试升级到稳定版本（如最新的9.x系列）或回退到已知正常的版本。

• 验证控制器元数据完整性：确认控制器类是否添加了@ApiTags等基础Swagger装饰器，自定义装饰器@Permissions是否破坏了NestJS的反射元数据。可暂时移除@Permissions测试，看参数是否恢复显示。

• 枚举类型的Swagger配置：如果EntityTypes是自定义枚举，需确保用@ApiEnumProperty或在Swagger文档构建时注册了该枚举，让Swagger能正确识别枚举类型的参数。

• 简化Swagger文档生成配置：在main.ts的SwaggerModule.createDocument配置中，暂时移除自定义的构建选项（如operationIdFactory、ignoreGlobalPrefix等），使用默认配置生成文档，排查是否为配置导致的参数解析异常。

内容的提问来源于stack exchange，提问作者nokiko