patch-spec: handmatig alternatief voor webpack: true

Wil je liever geen compilerplugin toevoegen, pas docsbestanden dan handmatig toe tijdens de build.

Geef de voorkeur aan de CLI-plugin, tenzij je een reden hebt om dat niet te doen

De CLI-plugin doet hetzelfde automatisch, bij elke build. Gebruik patch-spec (hieronder) in plaats daarvan als je liever geen compilerplugin toevoegt, bijvoorbeeld een build-pijplijn die niet de Nest CLI is, of een strikter beleid over wat er tijdens compilatie draait.

Waarom dit nodig is

Met "webpack": true in nest-cli.json (de gedocumenteerde standaard voor monorepo's met meerdere apps) werkt de runtime discovery van DocfyModule niet: webpack bundelt alles in één bundel en vult require.cache nooit met één entry per origineel bronbestand, waar die discovery van afhangt. Dit is architecturaal, geen op te lossen bug. Zie strict mode & webpack.

Pijplijn

bash
# 1. Start de app alleen om de live /api-json te krijgen
node dist/main.js &

# 2. Genereer een OpenAPI-document met alle docsbestanden al toegepast
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

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

Roep DocfyUiModule.setup() aan vóór SwaggerModule.setup() zodat de statische /api-json voorrang krijgt op de live versie.

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

Opties

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