patch-spec: ręczna alternatywa dla webpack: true

Jeśli wolisz nie dodawać pluginu kompilatora, aplikuj pliki docs w czasie builda ręcznie.

Preferuj plugin CLI, chyba że masz powód, by tego nie robić

The CLI plugin robi to samo automatycznie, przy każdym buildzie. Użyj patch-spec (poniżej) zamiast tego, jeśli wolisz nie dodawać pluginu kompilatora, na przykład pipeline builda inny niż Nest CLI, albo bardziej rygorystyczna polityka co do tego, co uruchamia się podczas kompilacji.

Dlaczego to konieczne

Z "webpack": true w nest-cli.json (udokumentowanym ustawieniem domyślnym dla monorepo z wieloma aplikacjami) runtime'owe wykrywanie DocfyModule nie działa: webpack łączy wszystko w jeden bundle i nigdy nie wypełnia require.cache jednym wpisem na oryginalny plik źródłowy, na czym to wykrywanie się opiera. To ograniczenie architektoniczne, nie błąd do naprawienia. Zobacz strict mode & webpack.

Pipeline

bash
# 1. Uruchom aplikację tylko po to, by uzyskać żywy /api-json
node dist/main.js &

# 2. Wygeneruj dokument OpenAPI z już zaaplikowanymi plikami docs
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Serwuj załatany dokument przez DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Wywołaj DocfyUiModule.setup() przed SwaggerModule.setup(), aby statyczny /api-json miał pierwszeństwo przed żywym.

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

Opcje

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

W 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