patch-spec: webpack: trueの手動代替手段

コンパイラプラグインを追加したくない場合、代わりにビルド時にdocsファイルを手動で適用します。

理由がない限りCLIプラグインを優先してください

The CLI pluginは同じことをビルドのたびに自動で行います。コンパイラプラグインを追加したくない場合(例えばNest CLIではないビルドパイプラインや、コンパイル時に実行するものについてより厳格なポリシーがある場合など)は、代わりに(下記の)patch-specを使ってください。

なぜこれが必要なのか

nest-cli.jsonに"webpack": trueがある場合(複数アプリを持つモノレポでドキュメント化されているデフォルト設定です)、DocfyModuleのランタイム検出は動作しません。webpackはすべてを単一のバンドルにまとめ、その検出が依存しているrequire.cacheを元のソースファイルごとに埋めることは決してないためです。これはアーキテクチャ上の問題であり、修正可能なバグではありません。strict mode & webpackを参照してください。

パイプライン

bash
# 1. 稼働中の /api-json を取得するためだけにアプリを起動
node dist/main.js &

# 2. すでにすべてのdocsファイルが適用されたOpenAPIドキュメントを生成
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. パッチ済みドキュメントをDocfyUiModule経由で配信
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

静的な/api-jsonを稼働中のものより優先させるため、DocfyUiModule.setup()をSwaggerModule.setup()より前に呼び出してください。

ts
// main.ts
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });
SwaggerModule.setup('api', app, document);

オプション

bash
npx nestjs-docfy patch-spec --spec <path-or-url> [options]
OptionDefaultDescription
--spec <path|url>(required)A local openapi.json, or a URL (e.g. a running app's /api-json)
--out <path>stdoutWhere to write the patched document
--root <path>.Project root directory
--tsconfig <path>auto-detectedPath to tsconfig.json
--pattern <glob>**/*.controller.tsGlob pattern to find controllers
--format <format>tsDocs file format to look for: ts or js
--quietfalseSuppress all output except errors

CIでの利用

.github/workflows/patch-spec.yml
# .github/workflows/patch-spec.yml
- name: Build patched OpenAPI document
  run: |
    node dist/main.js &
    sleep 2
    npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json