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.
¿Y el builder SWC?

Nada de esto aplica a "builder": "swc" — SWC sigue compilando un archivo por módulo, así que require.cache se rellena igual que con tsc, y el discovery en runtime de DocfyModule funciona con normalidad ahí. El único detalle específico de SWC no tiene relación con esta limitación: registrar el plugin de CLI bajo SWC necesita "typeCheck": true, cubierto en la sección Builder SWC de la guía del plugin.