patch-spec: alternativa manual para webpack: true

Se você preferir não adicionar um plugin de compilador, aplique docs files no build manualmente.

Prefira o plugin do CLI, a menos que tenha um motivo pra não

O plugin do CLI faz a mesma coisa automaticamente, a cada build. Use patch-spec (abaixo) em vez disso se você preferir não adicionar um plugin de compilador, por exemplo, um pipeline de build que não é o Nest CLI, ou uma política mais rígida sobre o que roda durante a compilação.

Por que isso é necessário

Com "webpack": true no nest-cli.json (o default documentado para monorepos com múltiplos apps), a discovery em runtime do DocfyModule não funciona: webpack empacota tudo num único bundle e nunca popula require.cache com uma entrada por arquivo-fonte original, que é do que essa discovery depende. Isso é arquitetural, não um bug corrigível. Ver strict e webpack.

Pipeline

bash
# 1. Suba a app apenas para obter o /api-json vivo
node dist/main.js &

# 2. Gere um documento OpenAPI já com todos os docs files aplicados
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

# 3. Sirva o documento com patch via DocfyUiModule
#    DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

Chame o DocfyUiModule.setup() antes do SwaggerModule.setup() para que o /api-json estático tenha precedência sobre o vivo.

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

Opções

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

No 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