Add support for @ApiParam in controllers.

[hiagodotme]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

@ApiParam is not supported in controllers, I don't know if there's any specific reason why it doesn't. But in the use case that I have, it makes sense to be able to use it directly in the controller.

In the example below, I will have to define @ApiParam('it_projeto') in each method, even if it is a param in the controller route.

import { Body, Controller, Get, Param, Post } from '@nestjs/common';
import { ApiParam, ApiTags } from '@nestjs/swagger';
import { CriarIntencaoDto } from './criar-intencao.dto';
import { IntencaoService } from './intencao.service';

@ApiTags('intencao')
@Controller('projeto/:it_projeto/intencao')
export class IntencaoController {
  constructor(private readonly intencaoService: IntencaoService) {}

  @ApiParam({
    name: 'it_projeto',
    type: 'number',
    description: 'Código do projeto',
  })
  @Get()
  listar(@Param() { it_projeto }) {
    return this.intencaoService.listar(it_projeto);
  }

  @ApiParam({
    name: 'it_projeto',
    type: 'number',
    description: 'Código do projeto',
  })
  @Post()
  criar(@Param() { it_projeto }, @Body() payload: CriarIntencaoDto) {
    return this.intencaoService.criar(it_projeto, payload);
  }
}

Describe the solution you'd like

I believe that support for class and method would already solve this problem. I don't particularly see any downsides.

Example

import { Body, Controller, Get, Param, Post } from '@nestjs/common';
import { ApiParam, ApiTags } from '@nestjs/swagger';
import { CriarIntencaoDto } from './criar-intencao.dto';
import { IntencaoService } from './intencao.service';

@ApiTags('intencao')
@ApiParam({
  name: 'it_projeto',
  type: 'number',
  description: 'Código do projeto',
})
@Controller('projeto/:it_projeto/intencao')
export class IntencaoController {
  constructor(private readonly intencaoService: IntencaoService) {}

  @Get()
  listar(@Param() { it_projeto }) {
    return this.intencaoService.listar(it_projeto);
  }

  @Post()
  criar(@Param() { it_projeto }, @Body() payload: CriarIntencaoDto) {
    return this.intencaoService.criar(it_projeto, payload);
  }
}

Teachability, documentation, adoption, migration strategy

On the page https://docs.nestjs.com/openapi/decorators I believe the only change for the user would be to add "Method/Controller" in the @ApiParam info.

What is the motivation / use case for changing the behavior?

Decrease decorator usage for expected parameters in the controller route.

[kamilmysliwiec]

Would you like to create a PR for this feature? Can use this old PR for reference #1332

[kamilmysliwiec]

#2213

[tomups]

@kamilmysliwiec is it really completed? The PR is still not merged.