Motywacja

Dekoratory Swaggera to dokumentacja. Nie mają nic wspólnego z routingiem, walidacją ani regułami biznesowymi, a mimo to i tak lądują w tym samym pliku.

Problem

Dekoratory Swaggera to dokumentacja. Nie mają nic wspólnego z routingiem, walidacją ani regułami biznesowymi, ale i tak lądują w tym samym pliku, podwajając rozmiar kontrolera i zagrzebując kod, który faktycznie ma znaczenie.

Przed i po

users.controller.ts z dekoratorami Swaggera rozrzuconymi wszędzie:

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

Konwencja

nestjs-docfy wymusza czystą granicę: kontrolery wyrażają zachowanie, pliki docs wyrażają dokumentację. Konwencja (*.controller.docs.ts) odzwierciedla to, jak NestJS już organizuje testy (*.controller.spec.ts), więc od pierwszego dnia wydaje się naturalna.