Modo strict & webpack

Duas configurações que definem o comportamento no boot: uma para CI, outra sobre uma limitação arquitetural.

strict: true

Passe { strict: true } em forRoot() para que a app lance no startup quando qualquer controller com @WithDocs() não tenha um companion file. Recomendado para CI, onde a falha rápida é preferível a um documento OpenAPI silenciosamente incompleto.

ts
DocfyModule.forRoot({ strict: true });

webpack: true

A discovery em runtime do DocfyModule não funciona aqui

Se seu nest-cli.json tem "webpack": true em compilerOptions, o pipeline em runtime do DocfyModule (discovery via @WithDocs() + require.cache) não vai funcionar, e não existe configuração que faça funcionar. Isso é arquitetural, e tem duas causas:

Primeiro, o webpack agrupa cada módulo em um único arquivo de bundle e nunca popula o require.cache do Node com uma entrada por arquivo-fonte original, que é do que o mecanismo de discovery depende. Você verá Could not locate source file for X para cada controller com @WithDocs().

Segundo, mesmo contornando essa busca, existe uma segunda barreira inevitável: um docs file carregado via require() de fora do bundle cria um objeto de classe estruturalmente diferente daquele que a aplicação em execução de fato usa internamente. Decorar essa cópia isolada não tem nenhum efeito sobre o documento que SwaggerModule.createDocument() realmente serve, e isso acontece silenciosamente, sem erro.

Duas formas de ter docs completos mesmo assim, em ordem de preferência:

  • O plugin do CLI (recomendado): corrige na raiz, automaticamente, a cada build, usando o mesmo mecanismo que o próprio plugin de CLI do @nestjs/swagger usa. Ver O plugin do CLI.
  • Use patch-spec: patch estático manual, orientado a CI, de um OpenAPI já buildado, sem depender de require.cache. Ver CLI: patch-spec e patch-spec: alternativa manual.
E o builder SWC?

Nada disso se aplica a "builder": "swc" — o SWC continua compilando um arquivo por módulo, então require.cache é populado do mesmo jeito que o tsc faz, e a discovery em runtime do DocfyModule funciona normalmente ali. O único detalhe específico do SWC não tem nada a ver com essa limitação: registrar o plugin do CLI sob SWC precisa de "typeCheck": true, coberto na seção Builder SWC do guia do plugin.