Motivatie

Swagger-decorators zijn documentatie. Ze hebben niets te maken met routing, validatie of businessregels, en toch belanden ze steeds in hetzelfde bestand.

Het probleem

Swagger-decorators zijn documentatie. Ze hebben niets te maken met routing, validatie of businessregels, maar belanden toch in hetzelfde bestand, waardoor de omvang van de controller verdubbelt en de code die er echt toe doet begraven raakt.

Voor en na

users.controller.ts met Swagger-decorators overal verspreid:

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

De conventie

nestjs-docfy dwingt een strikte scheiding af: controllers drukken gedrag uit, docsbestanden drukken documentatie uit. De conventie (*.controller.docs.ts) spiegelt hoe NestJS specs al organiseert (*.controller.spec.ts), dus voelt het meteen vertrouwd.