patch-spec: alternativa manuale per webpack: true

Se preferisci non aggiungere un plugin del compilatore, applica i file docs a mano in fase di build.

Preferisci il plugin CLI, a meno che tu non abbia un motivo per non farlo

Il plugin CLI fa la stessa cosa automaticamente, a ogni build. Usa patch-spec (sotto) invece se preferisci non aggiungere un plugin del compilatore, ad esempio con una pipeline di build che non è la Nest CLI, o una policy più severa su cosa gira durante la compilazione.

Perché è necessario

Con "webpack": true in nest-cli.json (il default documentato per i monorepo con più app), la discovery a runtime di DocfyModule non funziona: webpack racchiude tutto in un unico bundle e non popola mai require.cache con una voce per ogni file sorgente originale, che è proprio ciò da cui dipende quella discovery. Questo è architetturale, non un bug risolvibile. Vedi strict mode e webpack.

Pipeline

bash
# 1. Avvia l'app solo per ottenere il /api-json live
node dist/main.js &

# 2. Genera un documento OpenAPI con tutti i file docs già applicati
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Servi il documento con patch applicata tramite DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Chiama DocfyUiModule.setup() prima di SwaggerModule.setup() in modo che il /api-json statico abbia la precedenza su quello live.

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

Opzioni

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

Nel 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