CLIプラグイン

webpack: trueに対する推奨される修正方法です。ビルドのたびに自動で、覚えておくべき別ステップもありません。

これは@nestjs/swagger自身のCLIプラグインがwebpack: true下で動作するために使っているのと同じメカニズムです。webpackビルドであっても@ApiProperty()をすべてのDTOプロパティに付ける必要がないのはそのためです。Nest CLIは、TypeScriptコンパイラプラグインフック(compilerOptions.plugins)をtscとwebpack(ts-loader)のビルダーの両方に同じように渡します。

プラグインを登録する

nestjs-docfyをnest-cli.jsonに登録します。

nest-cli.json

{
  "compilerOptions": {
    "webpack": true,
    "plugins": ["nestjs-docfy"]
  }
}

main.ts

import { applyDocfyMetadata } from 'nestjs-docfy';

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, applyDocfyMetadata(document));

Option	Type	Default	Description
`metadataPath`	`string`	docfy-metadata.json next to the running entry file	Where to read the plugin-generated metadata from.
`strict`	`boolean`	`false`	Throw instead of warning when the metadata file is missing or invalid.

自動検出

プラグインの登録を忘れることは、ドキュメントなしでビルドが出荷されるまで気づきにくいものです。そのため、generateを実行するたびにnest-cli.jsonを確認し、プラグインなしでwebpack: trueが設定されている場合は警告を表示します。ファイルを手動で編集する代わりに--register-pluginを渡せば、代わりに修正してくれます。

bash

npx nestjs-docfy generate --register-plugin

これは意図的にオプトインです。コンパイラプラグインではなく意図的にpatch-specだけを使い続けるチームもあるため、generateは明示的に指示しない限りnest-cli.jsonを編集しません。既存のcompilerOptions.plugins配列に追加し(文字列形式・オブジェクト形式のどちらのエントリーもすでに登録済みとして認識します)、--dry-runを尊重します。

仕組み

nestjs-docfyのプラグインは、デコレーター構文を書き換えたりASTに触れたりすることは一切ありません。コンパイルのたびに、generate/check/patch-specがすでに行っているのとまったく同じ静的解析を(バンドルではなくソースツリーに対してts-morph経由で)再実行し、結果のパッチをビルド出力の隣にあるdocfy-metadata.jsonに書き出します。

そしてSwaggerModule.createDocument()の直後、applyDocfyMetadata()がそのファイルを読み込みマージします。require.cacheは一切関与せず、バンドルされたクラスの同一性の問題もありません。実行中のアプリに何かを計算させる必要が一切ないためです。

patch-specとの比較

Manual, CI-driven alternative

コンパイラプラグインを追加したくない場合(例えばNest CLIではないビルドパイプラインや、コンパイル時に実行するものについてより厳格なポリシーがある場合など)、patch-specはすでに構築済みのドキュメントに対して手動で同一のパッチを計算します。これはプラグインが存在する前は唯一の選択肢であり、一回限りのパッチ適用には今も有用です。

このページの内容

プラグインを登録する

自動検出

仕組み

patch-specとの比較