Some of @ApiOperation decorator options are being ignored or overwritten

[ivan-sennov]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

When @ApiOperation decorator is used, such options as "parameters", "tags" and "responses" are ignored and doesn't affect the resulting swagger json. You have to use @ApiResponse and other corresponding decorators to reach needed effect.

Code

@Controller('cats')
@ApiTags('cats')
class CatsController {
  @Get()
  @ApiOperation({
    // This works
    description: 'Find cats',
    summary: 'Short summary',
    operationId: 'findCats',

    // The next options are being ignored
    parameters: [{ name: 'color', in: 'query', schema: { type: 'string' } }],
    tags: ['search'],
    responses: {
      '2xx': {
        description: 'Cat',
        content: {
          // ...
        },
      },
    },
  })
  find(@Query query: Record<string, string>) {
    // ...
  }
}

Result

Minimum reproduction code

See example above

Steps to reproduce

No response

Expected behavior

When @ApiOperation decorator is used, all used options have the appropriate effect. If there are more specific decorators are used, such as @ApiResponse, they have a higher priority.

Package version

7.2.0

NestJS version

10.3.1

Node.js version

18.19.0

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

Sometimes there is no properly typed models or interfaces are used and you need to manually describe the entire endpoint, including the query parameters and response types. In such case it may be inconvenient to use the different decorators and I would like to use the mentioned one to cover all properties of operation. Moreover, the type ApiOperationOptions which @ApiOperation accepts as an options allows passing such things in it but never applies them, which can be misleading.

During my investigation, I found the next code in the SwaggerExplorer class:

swagger/lib/swagger-explorer.ts

Lines 95 to 104 in 6633c36

	const documentResolvers: DenormalizedDocResolvers = {
	root: [
	this.exploreRoutePathAndMethod,
	exploreApiOperationMetadata,
	exploreApiParametersMetadata.bind(null, this.schemas)
	],
	security: [exploreApiSecurityMetadata],
	tags: [exploreApiTagsMetadata],
	responses: [exploreApiResponseMetadata.bind(null, this.schemas)]
	};

Explorers are processed sequentially and, as a result, parameters and other mentioned fields which comes from ApiOperationExplorer are being overwritten by the next explorers here

swagger/lib/swagger-explorer.ts

Line 182 in 6633c36

return { ...metadata, ...exploredMetadata };

Thus, we can not manually set such properties with @ApiOperation decorator.

[mastermatt]

+1

When I discovered it wasn't possible to manually set a $ref for a header param via @ApiHeader, I was hoping I could get around it manually using @ApiOperation. Only to find params don't work at all in @ApiOperation.

[paulwer]

same here :(