patch-spec: manual alternative for webpack: true

If you'd rather not add a compiler plugin, apply docs files at build time by hand instead.

Prefer the CLI plugin, unless you have a reason not to

The CLI plugin does the same thing automatically, on every build. Use patch-spec (below) instead if you'd rather not add a compiler plugin, for example, a build pipeline that isn't the Nest CLI, or a stricter policy about what runs during compilation.

Why this is necessary

With "webpack": true in nest-cli.json (the documented default for monorepos with multiple apps), the DocfyModule runtime discovery doesn't work: webpack bundles everything into a single bundle and never populates require.cache with one entry per original source file, which is what that discovery depends on. This is architectural, not a fixable bug. See strict mode & webpack.

Pipeline

bash
# 1. Start the app just to get the live /api-json
node dist/main.js &

# 2. Generate an OpenAPI document with all docs files already applied
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Serve the patched document via DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Call DocfyUiModule.setup() before SwaggerModule.setup() so that the static /api-json takes precedence over the live one.

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

Options

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

In 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