Motivazione

I decorator Swagger sono documentazione. Non hanno nulla a che fare con routing, validazione o regole di business, eppure finiscono comunque mescolati nello stesso file.

Il problema

I decorator Swagger sono documentazione. Non hanno nulla a che fare con routing, validazione o regole di business, ma finiscono mescolati nello stesso file, raddoppiando la dimensione del controller e seppellendo il codice che conta davvero.

Prima e dopo

users.controller.ts con decorator Swagger sparsi ovunque:

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 convenzione

nestjs-docfy impone un confine netto: i controller esprimono comportamento, i file docs esprimono documentazione. La convenzione (*.controller.docs.ts) rispecchia come NestJS organizza già gli spec (*.controller.spec.ts), quindi risulta naturale fin dal primo giorno.