File naming convention
El discovery es automático. DocfyModule localiza el archivo fuente de cada controller vía la caché de módulos de Node.
Convención
El discovery es automático. DocfyModule localiza el archivo fuente de cada controller vía la caché de módulos de Node y resuelve la ruta companion: esto funciona igual bajo ts-node (desarrollo) y dist/ compilado (producción).
| Archivo controller | Archivo companion |
|---|---|
users.controller.ts | users.controller.docs.ts |
users.controller.js | users.controller.docs.js |
Barrel re-exports
Si tu controller también se exporta desde un barrel index.ts, asegúrate de que la clase se exporta directamente desde su propio archivo de módulo. nestjs-docfy prefiere .controller.ts sobre archivos barrel.
Modo de build webpack: true
Si tu nest-cli.json tiene "webpack": true bajo compilerOptions (el valor por defecto documentado para monorepos con varias apps), el pipeline en runtime de DocfyModule (el discovery vía @WithDocs() + require.cache descrito arriba) no va a funcionar, y no hay configuración que lo haga funcionar. Esto es arquitectónico:
- Webpack mete cada módulo en un único archivo bundle y nunca rellena el
require.cachede Node con una entrada por archivo fuente original, que es de lo que depende el mecanismo de discovery. VerásCould not locate source file for Xpara cada controller con@WithDocs(). - Incluso si esa búsqueda se sortea (por ejemplo, recuperando la ruta original desde el source map del bundle, saltándose el
require.cache), hay un segundo muro inevitable: un docs file requerido desde fuera del bundle crea un objeto de clase estructuralmente distinto al que la app en ejecución usa internamente. Decorar esa copia nueva no tiene ningún efecto sobre el documento queSwaggerModule.createDocument()realmente sirve. Esto ocurre en silencio, sin ningún error. - La única forma de sortear esto sería que el propio archivo controller importara su companion
.docs.ts(forzando a webpack a empaquetar ambos juntos), lo cual anula por completo el sentido de la convención: cero acoplamiento entre controller y documentación.
Cómo tener docs completos de todos modos
El plugin de CLI (recomendado): registra nestjs-docfy en compilerOptions.plugins de nest-cli.json y llama a applyDocfyMetadata() justo después de SwaggerModule.createDocument(). Arregla esto de raíz, automáticamente, en cada build. Consulta El plugin de CLI.
Use patch-spec como alternativa manual, impulsada por CI, si prefieres no añadir un plugin de compilador. Consulta patch-spec: alternativa manual. O deshabilita el bundling de webpack por completo: elimina "webpack": true (o ponlo en false) en nest-cli.json. Bajo la compilación por defecto basada en tsc, cada archivo fuente compila a su propio .js, así que require.cache naturalmente tiene una entrada por archivo y el discovery en runtime de DocfyModule funciona sin modificaciones.