NestJS中applyDecorators整合ApiOperation遇默认空装饰器覆盖问题

问题原因 #

这个空的openapi.ApiOperation({ description: "" })是@nestjs/swagger的CLI插件自动生成的——当插件检测到控制器方法没有直接添加ApiOperation装饰器时，会自动补一个空实例。即便你在组合装饰器中已经包含了ApiOperation，插件可能无法识别，依旧会生成空装饰器并排在组合装饰器之前，导致自定义配置被覆盖。

解决方案 #

方案1：禁用插件自动生成ApiOperation #

修改nest-cli.json中的Swagger插件配置，关闭自动生成空ApiOperation的功能，完全通过自定义组合装饰器管理接口文档：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "autoGenerateApiDocs": false,
          "autoGenerateTags": true // 按需保留自动生成标签功能
        }
      }
    ]
  }
}

配置后插件不再自动添加空ApiOperation，所有接口的操作描述都由你的组合装饰器控制。

方案2：显式设置description覆盖空值 #

在组合装饰器中为ApiOperation添加description字段，即使默认生成的空装饰器存在，后面的自定义配置也会合并覆盖它：

export function OApiDocumentationBasicRead(entity: string) {
  return applyDecorators(
    ApiOperation({
      summary: `Retrieves a single ${entity} given its ID`,
      description: `通过ID获取单个${entity}实例的详细信息` // 显式设置description，覆盖默认空值
    }),
    // ...其他需要组合的装饰器
  );
}

这种方法无需修改插件配置，直接通过自定义配置覆盖默认的空描述。

方案3：升级@nestjs/swagger到最新版本 #

部分旧版本的Swagger插件存在无法识别组合装饰器中ApiOperation的问题，升级到最新版本后，插件会检测到组合装饰器内的ApiOperation，从而不再生成空装饰器。

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