Convention de nommage des fichiers

Convention

La découverte est automatique. DocfyModule localise le fichier source de chaque contrôleur via le cache de modules de Node et résout le chemin compagnon : ça fonctionne de façon identique sous ts-node (développement) et en dist/ compilé (production).

Ré-exports barrel

mode de build webpack: true

Si ton nest-cli.json a "webpack": true sous compilerOptions (la valeur par défaut documentée pour les monorepos avec plusieurs apps), le pipeline runtime de DocfyModule (la découverte via @WithDocs() + require.cache décrite plus haut) ne fonctionnera pas, et aucune configuration ne le fait fonctionner. C'est architectural :

• 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().
• Même si cette recherche est contournée (par exemple, en récupérant le chemin d'origine depuis la source map du bundle, en évitant require.cache), il y a un second mur incontournable : un fichier docs requis depuis l'extérieur du bundle crée un objet de classe structurellement différent de celui que l'app en cours d'exécution utilise réellement en interne. Décorer cette copie fraîche n'a aucun effet sur le document que SwaggerModule.createDocument() sert réellement. Ça se produit silencieusement, sans erreur.
• La seule façon de contourner ça serait que le fichier contrôleur lui-même importe son compagnon .docs.ts (forçant webpack à bundler les deux ensemble), ce qui va à l'encontre de l'intérêt même de la convention : zéro couplage entre contrôleur et documentation.

Comment avoir une doc complète malgré tout

Le plugin CLI (recommandé) : enregistre nestjs-docfy dans compilerOptions.plugins de nest-cli.json et appelle applyDocfyMetadata() juste après SwaggerModule.createDocument(). Corrige ça à la racine, automatiquement, à chaque build. Voir Le plugin CLI.

Use patch-spec comme alternative manuelle pilotée par la CI si tu préfères ne pas ajouter de plugin de compilateur. Voir patch-spec : alternative manuelle. Ou désactive complètement le bundling webpack : retire "webpack": true (ou mets-le à false) dans nest-cli.json. Sous la compilation par défaut basée sur tsc, chaque fichier source compile vers son propre .js, donc require.cache a naturellement une entrée par fichier et la découverte runtime de DocfyModule fonctionne sans modification.