patch-spec: manuelle Alternative für webpack: true

Möchtest du lieber kein Compiler-Plugin hinzufügen, wende Docs-Dateien stattdessen von Hand zur Build-Zeit an.

Bevorzuge das CLI-Plugin, außer du hast einen Grund dagegen

Das CLI-Plugin macht dasselbe automatisch, bei jedem Build. Nutz stattdessen patch-spec (unten), wenn du lieber kein Compiler-Plugin hinzufügen möchtest, zum Beispiel bei einer Build-Pipeline, die nicht die Nest-CLI ist, oder einer strikteren Policy dazu, was während der Kompilierung läuft.

Warum das nötig ist

Mit "webpack": true in nest-cli.json (der dokumentierte Standard für Monorepos mit mehreren Apps) funktioniert die Runtime-Discovery von DocfyModule nicht: Webpack bündelt alles in ein einziges Bundle und befüllt require.cache nie mit einem Eintrag pro ursprünglicher Quelldatei, worauf diese Erkennung angewiesen ist. Das ist architektonisch bedingt, kein behebbarer Bug. Siehe strict mode & webpack.

Pipeline

bash
# 1. App nur starten, um das laufende /api-json zu bekommen
node dist/main.js &

# 2. Ein OpenAPI-Dokument erzeugen, in das alle Docs-Dateien schon angewendet sind
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Das gepatchte Dokument über DocfyUiModule ausliefern
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Ruf DocfyUiModule.setup() vor SwaggerModule.setup() auf, damit die statische /api-json Vorrang vor der laufenden hat.

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

Optionen

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