Мотивация

Декораторы Swagger относятся к документации. К маршрутизации, валидации и бизнес-правилам они отношения не имеют, но всё равно оказываются в том же файле.

Проблема

Декораторы Swagger относятся к документации. К маршрутизации, валидации и бизнес-правилам они отношения не имеют, но оказываются в том же файле, удваивают размер контроллера и хоронят под собой тот код, ради которого он написан.

До и после

users.controller.ts, где декораторы Swagger рассыпаны по всему файлу:

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

Соглашение

nestjs-docfy проводит чёткую границу: контроллеры описывают поведение, docs-файлы описывают документацию. Соглашение (*.controller.docs.ts) повторяет то, как NestJS уже раскладывает тесты (*.controller.spec.ts), так что привыкать к нему не придётся.