strict mode & webpack

Dos configuraciones que dan forma al comportamiento en el arranque: una para CI, la otra sobre una limitación arquitectónica.

strict: true

Pasa { strict: true } a forRoot() para que la app lance un error al arrancar cuando algún controller con @WithDocs() no tenga archivo companion. Recomendado para CI, donde fallar rápido es preferible a un documento OpenAPI incompleto en silencio.

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

webpack: true

El discovery en runtime de DocfyModule no funciona aquí

Si tu nest-cli.json tiene "webpack": true bajo compilerOptions, el pipeline en runtime de DocfyModule (discovery vía @WithDocs() + require.cache) no va a funcionar, y no hay configuración que lo haga funcionar. Esto es arquitectónico, y tiene dos causas:

Primero, webpack empaqueta cada módulo en un único archivo bundle y nunca rellena el require.cache de Node con una entrada por archivo fuente original, que es de lo que depende el mecanismo de discovery. Verás Could not locate source file for X para cada controller con @WithDocs().

Segundo, incluso sorteando esa búsqueda, hay una segunda barrera inevitable: un docs file cargado vía require() desde fuera del bundle crea un objeto de clase estructuralmente distinto al que la aplicación en ejecución realmente usa internamente. Decorar esa copia aislada no tiene ningún efecto sobre el documento que SwaggerModule.createDocument() realmente sirve, y esto ocurre en silencio, sin ningún error.

Dos formas de tener la documentación completa de todos modos, en orden de preferencia:

  • El plugin de CLI (recomendado): lo arregla de raíz, automáticamente, en cada build, usando el mismo mecanismo que usa el propio plugin de CLI de @nestjs/swagger. Consulta El plugin de CLI.
  • Use patch-spec: un parche estático manual, impulsado por CI, de un documento OpenAPI ya construido, sin dependencia de require.cache. Consulta CLI: patch-spec y patch-spec: alternativa manual.