単なるSwaggerドキュメントを
超えて。

nestjs-docfy コンパニオンファイル命名規約を使って、Swagger/OpenAPIドキュメントをコントローラーのロジックから切り離します。Nestがすでに *.controller.spec.ts.

Installation

npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadata

最新リリース v0.13.0ライセンス MIT

規約によるコンパニオンファイル

users.controller.ts → users.controller.docs.ts。Nestがすでに*.controller.spec.tsで使っているのと同じパターンです。

CIゲート付きCLI

check、coverage --min、lint、patch-spec。ドキュメントが欠けているとビルドを失敗させます。

自動型推論

インターフェース、class-validator、@HttpCode()が、追加のデコレーターなしでOpenAPIスキーマになります。

AIファーストなDocfy UI

すべてのエンドポイントにCopy for AIボタンを備えたリファレンスUIです。LLMへの貼り付けに最適です。

docfy-ui: AIファーストなリファレンスビューア

nestjs-docfyが組み立てるOpenAPIスペックは、docfy-uiが描画するものでもあります。別の設定は不要で、同じ唯一の情報源を共有します。

Copy for AI: $ref付きの生JSONダンプではなく、決定的でLLM向けのエンドポイントのサマリー
⌘Kですべてのエンドポイントを瞬時に検索
スペックからそのまま生成された、エンドポイントごとの完全なリクエスト/レスポンス詳細

docfy-ui detalhe de endpoint com Copy for AI

実際にはどう見えるか

Before: デコレーターに埋もれたコントローラー。After: ルートだけが残り、ドキュメントはコンパニオンファイルの中で隣り合って生きています。

users.controller.ts

@WithDocs()
@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}

users.controller.docs.ts

import { docs } from 'nestjs-docfy';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UsersController } from './users.controller';

docs(UsersController, {
  classDecorators: [ApiTags('users')],
  methods: {
    findOne: [
      ApiOperation({ summary: 'Get user by id' }),
      ApiResponse({ status: 200, description: 'OK', type: UserDto }),
      ApiResponse({ status: 404, description: 'User not found' }),
    ],
  },
});

起動時のみ、リクエストごとのオーバーヘッドはゼロインラインデコレーターと同じOpenAPI出力*.spec.tsのようなコンパニオンファイル規約

モンキーパッチなし、ランタイムプロキシなし

正しいタイミングとReflectメタデータだけです。

コンパニオンファイルを書く

users.controller.docs.tsがdocs(UsersController, { ... })を呼び出します。ただのSwaggerデコレーターを、別のファイルに書いているだけです。

起動時に検出される

DocfyModule.forRoot()が命名規約経由でそれを見つけ、SwaggerModule.createDocument()が実行される前に、コントローラーのメソッドへReflectメタデータを書き込みます。

同一のOpenAPI出力

SwaggerModuleは、デコレーターがコントローラーにインラインで書かれていた場合とまったく同じメタデータを見ます。

単なるSwaggerドキュメントを超えて。