動機

Swaggerデコレーターはドキュメントです。ルーティングやバリデーション、ビジネスルールとは無関係ですが、それでも同じファイルに混ざり込んでしまいます。

問題

Swaggerデコレーターはドキュメントです。ルーティングやバリデーション、ビジネスルールとは無関係ですが、同じファイルに混ざり込んでしまい、コントローラーのサイズを倍増させ、本当に重要なコードを埋もれさせてしまいます。

導入前後

Swaggerデコレーターが随所に散らばったusers.controller.ts:

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がすでにspecを整理している方法(*.controller.spec.ts)を反映しているため、初日から自然に感じられます。