既存のAPIをドキュメント化する

手順

1. パッケージをインストールします(Installationを参照)。
2. DocfyModule.forRoot()をAppModuleに登録します。
   app.module.ts

   // app.module.ts
   import { Module } from '@nestjs/common';
   import { DocfyModule } from 'nestjs-docfy';
   
   @Module({
     imports: [DocfyModule.forRoot()],
   })
   export class AppModule {}

3. 既存のコントローラーに@WithDocs()を追加します。
   users.controller.ts

   // users.controller.ts
   import { Controller, Get, Post, Body } from '@nestjs/common';
   import { WithDocs } from 'nestjs-docfy';
   
   @WithDocs()
   @Controller('users')
   export class UsersController {
     // route handlers only, no Swagger decorators here
   }

4. npx nestjs-docfy generateを実行して(先に--dry-runで何が書き込まれるかプレビューしても構いません)、コントローラーの隣に*.controller.docs.tsファイルを生成します。docs()で推論されたサマリーとレスポンスがあらかじめ埋め込まれており、コントローラーのロジックには一切触れません。
   bash

   npx nestjs-docfy generate --dry-run
   npx nestjs-docfy generate

   users.controller.docs.ts (generated)

   // Generated by nestjs-docfy@x.y.z. Edit freely, use --force to merge new methods, --overwrite to regenerate from scratch
   import { docs } from 'nestjs-docfy';
   import { ApiTags, ApiOperation, ApiResponse, ApiBody } from '@nestjs/swagger';
   import { UsersController } from './users.controller';
   import { CreateUserDto } from './dto/create-user.dto';
   import { UserEntity } from './entities/user.entity';
   
   docs(UsersController, {
     classDecorators: [ApiTags('users')],
     methods: {
       // GET / → async findAll(): Promise<UserEntity[]>
       findAll: [
         ApiOperation({ summary: 'Find all' }),
         ApiResponse({ status: 200, description: 'OK', type: [UserEntity] }),
       ],
   
       // POST / → async create(dto: CreateUserDto): Promise<UserEntity>
       create: [
         ApiOperation({ summary: 'Create' }),
         ApiBody({ type: CreateUserDto }),
         ApiResponse({ status: 201, description: 'Created', type: UserEntity }),
         ApiResponse({ status: 400, description: 'Bad Request' }),
       ],
     },
   });

5. ドメイン固有の内容を生成されたファイルに書き加えます。
6. npx nestjs-docfy coverageを実行して進捗を計測し、反復します。
   bash

   npx nestjs-docfy coverage

   text

   Controllers: 42
   Endpoints: 187
   
   Documented: 174
   Missing docs: 13
   
   Coverage: 93.0%

7. 満足したらDocfyModule.forRoot({ strict: true })を有効にし、docsファイルなしでマークされたコントローラーが起動時に失敗するようにします。
   ts

   DocfyModule.forRoot({ strict: true });