Convenção de nomes
Discovery é automático. DocfyModule localiza o arquivo-fonte de cada controller via module cache do Node.
Convenção
Discovery é automático. DocfyModule localiza o arquivo-fonte de cada controller via cache de módulos do Node e resolve o path do companheiro: isso funciona identicamente em ts-node (desenvolvimento) e em dist/ compilado (produção).
| Arquivo do controller | Arquivo companheiro |
|---|---|
users.controller.ts | users.controller.docs.ts |
users.controller.js | users.controller.docs.js |
Barrel re-exports
Se seu controller também é exportado de um barrel index.ts, garanta que a classe seja exportada diretamente do seu próprio arquivo de módulo. nestjs-docfy prefere .controller.ts a arquivos barrel.
Não suportado: modo de build webpack: true do NestJS CLI
Se seu nest-cli.json tem "webpack": true em compilerOptions (o default documentado para monorepos com múltiplos apps), o nestjs-docfy não vai funcionar, e não existe configuração que faça funcionar. Isso é arquitetural, não um bug a ser corrigido:
- Webpack inlina cada módulo em um arquivo de bundle e nunca popula o
require.cachedo Node com uma entrada por arquivo-fonte original, que é do que o mecanismo de discovery depende. Você veráCould not locate source file for Xpara cada controller com@WithDocs(). - Mesmo se esse lookup for contornado (por exemplo, recuperando o path original a partir do source map do bundle, pulando o
require.cache), há uma segunda parede inevitável: um docs file requerido de fora do bundle cria um objeto de classe estruturalmente diferente do que a app em execução usa internamente. Decorar essa cópia fresca não tem efeito no documento queSwaggerModule.createDocument()de fato serve. Isso acontece silenciosamente, sem erro. - O único jeito de contornar isso seria o próprio arquivo do controller importar seu companheiro
.docs.ts(forçando o webpack a bundlar os dois juntos), o que anula todo o ponto da convenção: zero acoplamento entre controller e documentação.
Como resolver
Se você precisa do nestjs-docfy, desabilite o bundling do webpack: remova "webpack": true (ou defina como false) no nest-cli.json. Sob a compilação default baseada em tsc, cada arquivo-fonte (incluindo cada *.controller.docs.ts) é compilado para seu próprio .js em dist/, então require.cache naturalmente tem uma entrada por arquivo e o discovery funciona.
Se você não pode desligar o webpack, use o comando patch-spec como fluxo alternativo.