patch-spec: alternativa manual para webpack: true

Si prefieres no añadir un plugin de compilador, aplica los docs files en build time a mano en su lugar.

Prefiere el plugin de CLI, a menos que tengas una razón para no hacerlo

El plugin de CLI hace lo mismo automáticamente, en cada build. Usa patch-spec (más abajo) en su lugar si prefieres no añadir un plugin de compilador, por ejemplo, un pipeline de build que no es el Nest CLI, o una política más estricta sobre qué se ejecuta durante la compilación.

Por qué esto es necesario

Con "webpack": true en nest-cli.json (el valor por defecto documentado para monorepos con varias apps), el discovery en runtime de DocfyModule no funciona: webpack mete todo en un único bundle y nunca rellena require.cache con una entrada por archivo fuente original, que es de lo que depende ese discovery. Esto es arquitectónico, no un bug arreglable. Consulta strict mode & webpack.

Pipeline

bash
# 1. Arranca la app solo para obtener el /api-json en vivo
node dist/main.js &

# 2. Genera un documento OpenAPI con todos los docs files ya aplicados
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Sirve el documento parcheado vía DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Llama a DocfyUiModule.setup() antes de SwaggerModule.setup() para que el /api-json estático tenga prioridad sobre el en vivo.

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

Opciones

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

En 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