ファイル命名規則
検出は自動です。DocfyModuleはNodeのモジュールキャッシュ経由で各コントローラーのソースファイルを特定します。
規約
検出は自動です。DocfyModuleはNodeのモジュールキャッシュ経由で各コントローラーのソースファイルを特定し、コンパニオンのパスを解決します。これはts-node(開発時)とコンパイル済みのdist/(本番)のどちらでも同じように動作します。
| コントローラーファイル | コンパニオンファイル |
|---|---|
users.controller.ts | users.controller.docs.ts |
users.controller.js | users.controller.docs.js |
バレルの再エクスポート
コントローラーがバレルのindex.tsからもエクスポートされている場合、クラス自体は必ずそのモジュールファイルから直接エクスポートしてください。nestjs-docfyはバレルファイルより.controller.tsを優先します。
webpack: trueビルドモード
nest-cli.jsonのcompilerOptions配下に"webpack": trueがある場合(複数アプリを持つモノレポでドキュメント化されているデフォルト設定です)、DocfyModuleのランタイムパイプライン(上で説明した@WithDocs() + require.cacheによる検出)は動作せず、動作させる設定も存在しません。これはアーキテクチャ上の問題です。
- Webpackはすべてのモジュールを単一のバンドルファイルへインライン化し、検出メカニズムが依存しているNodeの
require.cacheを、元のソースファイルごとに1エントリーずつ埋めることはありません。@WithDocs()が付いたすべてのコントローラーでCould not locate source file for Xが表示されるはずです。 - そのルックアップを回避したとしても(例えばバンドルのソースマップから元のパスを復元し
require.cacheを使わないようにしても)、避けられない第二の壁があります。バンドルの外から要求されたdocsファイルは、実行中のアプリが内部で実際に使っているクラスとは構造的に異なるクラスオブジェクトを生成します。その新しいコピーをデコレートしても、SwaggerModule.createDocument()が実際に提供するドキュメントには影響しません。これはエラーもなく、静かに起きます。 - これを回避する唯一の方法は、コントローラーファイル自体が
.docs.tsコンパニオンをimportし、webpackに両方を一緒にバンドルさせることですが、それではコントローラーとドキュメントの間の結合をゼロにするというこの規約の意義そのものが失われます。
それでも完全なドキュメントを得る方法
CLIプラグイン(推奨): nestjs-docfyをnest-cli.jsonのcompilerOptions.pluginsに登録し、SwaggerModule.createDocument()の直後にapplyDocfyMetadata()を呼び出してください。ビルドのたびに自動でこれを根本から修正します。The CLI pluginを参照してください。
コンパイラプラグインを追加したくない場合の手動でCI駆動の代替手段としてUse patch-specもあります。patch-spec: manual alternativeを参照してください。あるいはwebpackバンドルを完全に無効化する方法もあります。nest-cli.jsonから"webpack": trueを削除する(またはfalseに設定する)だけです。デフォルトのtscベースのコンパイルでは、各ソースファイルが独自の.jsにコンパイルされるため、require.cacheには自然にファイルごとに1エントリーが存在し、DocfyModuleのランタイム検出は変更なしで動作します。