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.
Modo de build webpack: true
Se seu nest-cli.json tem "webpack": true em compilerOptions (o default documentado para monorepos com múltiplos apps), o pipeline em runtime do DocfyModule (a discovery via @WithDocs() + require.cache descrita acima) não vai funcionar, e não existe configuração que faça funcionar. Isso é arquitetural:
- 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 ter docs completos mesmo assim
O plugin do CLI (recomendado): registre o nestjs-docfy em compilerOptions.plugins do nest-cli.json e chame applyDocfyMetadata() logo após SwaggerModule.createDocument(). Corrige isso na raiz, automaticamente, a cada build. Ver O plugin do CLI.
Use patch-spec como alternativa manual, orientada a CI, se preferir não adicionar um plugin de compilador. Ver patch-spec: alternativa manual. Ou desabilite o bundling do webpack completamente: remova "webpack": true (ou defina como false) no nest-cli.json. Sob a compilação default baseada em tsc, cada arquivo-fonte é compilado para seu próprio .js, então require.cache naturalmente tem uma entrada por arquivo e a discovery em runtime do DocfyModule funciona sem modificação.