Motivação

Decorators Swagger são documentação. Não têm nada a ver com routing, validação ou regras de negócio, mas mesmo assim acabam misturados no mesmo arquivo.

O problema

Decorators Swagger são documentação. Eles não têm nada a ver com routing, validação ou regras de negócio, mas acabam misturados no mesmo arquivo, dobrando o tamanho do controller e enterrando o código que de fato importa.

Antes e depois

users.controller.ts com decorators Swagger espalhados:

users.controller.ts
// users.controller.ts
@ApiTags("users")
@Controller("users")
export class UsersController {
  @Get()
  @ApiOperation({ summary: "List all users" })
  @ApiResponse({ status: 200, description: "OK", type: [UserEntity] })
  findAll(): Promise<UserEntity[]> {
    return this.usersService.findAll();
  }

  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiBody({ type: CreateUserDto })
  @ApiResponse({ status: 201, description: "Created", type: UserEntity })
  @ApiResponse({ status: 400, description: "Bad Request" })
  create(@Body() dto: CreateUserDto): Promise<UserEntity> {
    return this.usersService.create(dto);
  }
}

A convenção

O nestjs-docfy impõe uma fronteira limpa: controllers expressam comportamento, docs files expressam documentação. A convenção (*.controller.docs.ts) espelha como o NestJS já organiza specs (*.controller.spec.ts), então parece natural desde o primeiro dia.