Motivación

Los decorators de Swagger son documentación. No tienen nada que ver con routing, validación o reglas de negocio, y aun así terminan mezclados en el mismo archivo.

El problema

Los decorators de Swagger son documentación. No tienen nada que ver con routing, validación o reglas de negocio, pero terminan mezclados en el mismo archivo, duplicando el tamaño del controller y enterrando el código que de verdad importa.

Antes y después

users.controller.ts con decorators de Swagger esparcidos por todas partes:

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);
  }
}

La convención

nestjs-docfy impone un límite claro: los controllers expresan comportamiento, los docs files expresan documentación. La convención (*.controller.docs.ts) refleja cómo NestJS ya organiza los specs (*.controller.spec.ts), así que se siente natural desde el primer día.