Convenzione di denominazione dei file
La discovery è automatica. DocfyModule localizza il file sorgente di ogni controller tramite la cache dei moduli di Node.
Convenzione
La discovery è automatica. DocfyModule localizza il file sorgente di ogni controller tramite la cache dei moduli di Node e risolve il percorso companion: questo funziona in modo identico sia sotto ts-node (sviluppo) sia con dist/ compilato (produzione).
| File controller | File companion |
|---|---|
users.controller.ts | users.controller.docs.ts |
users.controller.js | users.controller.docs.js |
Re-export tramite barrel
Se il tuo controller viene esportato anche da un barrel index.ts, assicurati che la classe sia esportata direttamente dal proprio file di modulo. nestjs-docfy preferisce .controller.ts ai file barrel.
Modalità build webpack: true
Se il tuo nest-cli.json ha "webpack": true sotto compilerOptions (il default documentato per i monorepo con più app), la pipeline runtime di DocfyModule (la discovery @WithDocs() + require.cache descritta sopra) non funzionerà, e non esiste una configurazione che la faccia funzionare. Questo è architetturale:
- Webpack racchiude ogni modulo in un unico file bundle e non popola mai
require.cachedi Node con una voce per ogni file sorgente originale, che è proprio ciò da cui dipende il meccanismo di discovery. VedraiCould not locate source file for Xper ogni controller con@WithDocs(). - Anche aggirando questa ricerca (ad esempio recuperando il percorso originale dalla source map del bundle, saltando
require.cache), c'è un secondo muro inevitabile: un file docs richiesto dall'esterno del bundle crea un oggetto classe strutturalmente diverso da quello usato internamente dall'app in esecuzione. Decorare quella copia appena creata non ha alcun effetto sul documento cheSwaggerModule.createDocument()serve davvero. Questo accade in silenzio, senza errori. - L'unico modo per aggirare questo sarebbe far importare al file controller stesso il proprio companion
.docs.ts(costringendo webpack a impacchettarli insieme), il che vanifica l'intero scopo della convenzione: zero accoppiamento tra controller e documentazione.
Come avere comunque documentazione completa
Il plugin CLI (consigliato): registra nestjs-docfy in compilerOptions.plugins di nest-cli.json e chiama applyDocfyMetadata() subito dopo SwaggerModule.createDocument(). Risolve il problema alla radice, automaticamente, a ogni build. Vedi Il plugin CLI.
Use patch-spec come alternativa manuale guidata dalla CI, se preferisci non aggiungere un plugin del compilatore. Vedi patch-spec: alternativa manuale. Oppure disabilita del tutto il bundling webpack: rimuovi "webpack": true (o impostalo a false) in nest-cli.json. Con la compilazione predefinita basata su tsc, ogni file sorgente viene compilato nel proprio .js, quindi require.cache ha naturalmente una voce per file e la discovery a runtime di DocfyModule funziona senza modifiche.