patch-spec: ручная альтернатива для webpack: true

Если добавлять плагин компилятора не хочется, применяйте docs-файлы во время сборки вручную.

Берите плагин CLI, если нет причин поступить иначе

Плагин CLI делает то же самое автоматически, на каждой сборке. К patch-spec ниже стоит переходить, когда добавлять плагин компилятора не хочется: например, сборка идёт не через Nest CLI или у вас строже правила насчёт того, что выполняется во время компиляции.

Зачем это нужно

При "webpack": true в nest-cli.json (документированное значение по умолчанию для монорепозиториев с несколькими приложениями) обнаружение DocfyModule в рантайме не работает: webpack складывает всё в один бандл и не заполняет require.cache записями по каждому исходному файлу, а обнаружение опирается именно на них. Это архитектурное свойство, а не баг, который можно починить. См. Режим strict и webpack.

Конвейер

bash
# 1. Поднимаем приложение только ради живого /api-json
node dist/main.js &

# 2. Собираем документ OpenAPI с уже применёнными docs-файлами
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Отдаём пропатченный документ через DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Вызывайте DocfyUiModule.setup() до SwaggerModule.setup(), чтобы статический /api-json оказался важнее живого.

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

Параметры

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

В 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