strict mode e webpack

Due impostazioni che modellano il comportamento all'avvio: una per la CI, l'altra riguarda un limite architetturale.

strict: true

Passa { strict: true } a forRoot() in modo che l'app sollevi un errore all'avvio quando un controller con @WithDocs() non ha un file companion. Consigliato per la CI, dove fallire subito è preferibile a un documento OpenAPI silenziosamente incompleto.

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

webpack: true

La discovery a runtime di DocfyModule qui non funziona

Se il tuo nest-cli.json ha "webpack": true sotto compilerOptions, la pipeline runtime di DocfyModule (discovery via @WithDocs() + require.cache) non funzionerà, e non esiste una configurazione che la faccia funzionare. Questo è architetturale, e ha due cause:

Primo, webpack impacchetta ogni modulo in un unico file bundle e non popola mai require.cache di Node con una voce per ogni file sorgente originale, che è proprio ciò da cui dipende il meccanismo di discovery. Vedrai Could not locate source file for X per ogni controller con @WithDocs().

Secondo, anche aggirando quella ricerca, c'è una seconda barriera inevitabile: un file docs caricato con require() dall'esterno del bundle crea un oggetto classe strutturalmente diverso da quello che l'applicazione in esecuzione usa realmente al suo interno. Decorare quella copia isolata non ha alcun effetto sul documento che SwaggerModule.createDocument() serve davvero, e questo accade in silenzio, senza errori.

Due modi per ottenere comunque la documentazione completa, in ordine di preferenza:

  • Il plugin CLI (consigliato): risolve il problema alla radice, automaticamente, a ogni build, usando lo stesso meccanismo del plugin CLI di @nestjs/swagger stesso. Vedi Il plugin CLI.
  • Use patch-spec: una patch statica manuale guidata dalla CI su un documento OpenAPI già costruito, senza dipendere da require.cache. Vedi CLI: patch-spec e patch-spec: alternativa manuale.