mode strict & webpack

Deux réglages qui façonnent le comportement au démarrage : l'un pour la CI, l'autre concerne une limitation architecturale.

strict: true

Passe { strict: true } à forRoot() pour que l'app lève une erreur au démarrage quand un contrôleur avec @WithDocs() n'a pas de fichier compagnon. Recommandé en CI, où échouer vite est préférable à un document OpenAPI silencieusement incomplet.

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

webpack: true

La découverte runtime de DocfyModule ne fonctionne pas ici

Si ton nest-cli.json a "webpack": true sous compilerOptions, le pipeline runtime de DocfyModule (la découverte via @WithDocs() + require.cache) ne fonctionnera pas, et aucune configuration ne le fait fonctionner. C'est architectural, pour deux raisons :

D'abord, webpack regroupe chaque module dans un seul fichier bundle et ne remplit jamais le require.cache de Node avec une entrée par fichier source d'origine, ce dont dépend le mécanisme de découverte. Tu verras Could not locate source file for X pour chaque contrôleur avec @WithDocs().

Ensuite, même en contournant cette recherche, il y a un second obstacle incontournable : un fichier docs chargé via require() depuis l'extérieur du bundle crée un objet de classe structurellement différent de celui que l'application en cours d'exécution utilise réellement en interne. Décorer cette copie isolée n'a strictement aucun effet sur le document que SwaggerModule.createDocument() sert réellement, et ça se produit silencieusement, sans erreur.

Deux façons d'avoir quand même une documentation complète, par ordre de préférence :

  • Le plugin CLI (recommandé) : corrige ça à la racine, automatiquement, à chaque build, en utilisant le même mécanisme que le plugin CLI de @nestjs/swagger lui-même. Voir Le plugin CLI.
  • Use patch-spec : un patch statique manuel, piloté par la CI, d'un document OpenAPI déjà construit, sans dépendance à require.cache. Voir CLI : patch-spec et patch-spec : alternative manuelle.