strictモードとwebpack

起動時の挙動を左右する2つの設定です。一方はCI向け、もう一方はアーキテクチャ上の制約についてです。

strict: true

{ strict: true }をforRoot()に渡すと、@WithDocs()が付いているのにコンパニオンファイルが見つからないコントローラーがある場合、アプリが起動時に例外を投げるようになります。早期に失敗するほうが、静かに不完全なOpenAPIドキュメントになるより望ましいCI環境で推奨されます。

ts
DocfyModule.forRoot({ strict: true });

webpack: true

DocfyModuleのランタイム検出はここでは動作しません

nest-cli.jsonのcompilerOptions配下に"webpack": trueがある場合、DocfyModuleのランタイムパイプライン(@WithDocs() + require.cacheによる検出)は動作せず、動作させる設定も存在しません。これはアーキテクチャ上の問題で、原因は2つあります。

まず、webpackはすべてのモジュールを単一のバンドルファイルへインライン化し、検出メカニズムが依存しているNodeのrequire.cacheを、元のソースファイルごとに1エントリーずつ埋めることはありません。@WithDocs()が付いたすべてのコントローラーでCould not locate source file for Xが表示されるはずです。

次に、そのルックアップを回避したとしても、避けられない第二の壁があります。バンドルの外からrequire()で読み込まれたdocsファイルは、実行中のアプリケーションが内部で実際に使っているクラスとは構造的に異なるクラスオブジェクトを生成します。その孤立したコピーをデコレートしても、SwaggerModule.createDocument()が実際に提供するドキュメントにはまったく影響しません。しかもこれはエラーもなく、静かに起きます。

それでも完全なドキュメントを得る方法は2つあり、推奨順に並べると次の通りです。

  • CLIプラグイン(推奨): @nestjs/swagger自身のCLIプラグインと同じメカニズムを使い、ビルドのたびに自動でこれを根本から修正します。The CLI pluginを参照してください。
  • Use patch-spec: require.cacheに一切依存しない、手動でCI駆動の、すでに構築済みのOpenAPIドキュメントに対する静的パッチです。CLI: patch-specとpatch-spec: manual alternativeを参照してください。