Motivation

Swagger-Decorators sind Dokumentation. Sie haben nichts mit Routing, Validierung oder Business-Regeln zu tun, landen aber trotzdem in derselben Datei.

Das Problem

Swagger-Decorators sind Dokumentation. Sie haben nichts mit Routing, Validierung oder Business-Regeln zu tun, landen aber in derselben Datei, verdoppeln so die Größe des Controllers und begraben den Code, der eigentlich zählt.

Vorher und nachher

users.controller.ts mit über die ganze Datei verstreuten Swagger-Decorators:

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

Die Konvention

nestjs-docfy erzwingt eine klare Grenze: Controller drücken Verhalten aus, Docs-Dateien drücken Dokumentation aus. Die Konvention (*.controller.docs.ts) spiegelt, wie NestJS Specs bereits organisiert (*.controller.spec.ts), und fühlt sich deshalb von Tag eins an vertraut an.