Namenskonvention für Dateien

Die Erkennung läuft automatisch. DocfyModule findet die Quelldatei jedes Controllers über Nodes Modul-Cache.

Konvention

Die Erkennung läuft automatisch. DocfyModule findet die Quelldatei jedes Controllers über Nodes Modul-Cache und löst den Companion-Pfad auf: Das funktioniert identisch unter ts-node (Entwicklung) und kompiliertem dist/ (Produktion).

Controller-DateiCompanion-Datei
users.controller.tsusers.controller.docs.ts
users.controller.jsusers.controller.docs.js

Barrel-Re-Exports

Barrel-Re-Exports

Wird dein Controller auch aus einer Barrel-index.ts exportiert, stell sicher, dass die Klasse direkt aus ihrer eigenen Moduldatei exportiert wird. nestjs-docfy bevorzugt .controller.ts gegenüber Barrel-Dateien.

webpack: true Build-Modus

Hat deine nest-cli.json unter compilerOptions "webpack": true gesetzt (der dokumentierte Standard für Monorepos mit mehreren Apps), funktioniert die Runtime-Pipeline von DocfyModule (die oben beschriebene @WithDocs()- + require.cache-Erkennung) nicht, und es gibt keine Konfiguration, die das ändert. Das ist architektonisch bedingt:

  • Webpack inlined jedes Modul in eine einzige Bundle-Datei und befüllt Nodes require.cache nie mit einem Eintrag pro ursprünglicher Quelldatei, worauf der Erkennungsmechanismus angewiesen ist. Du siehst Could not locate source file for X für jeden Controller mit @WithDocs().
  • Selbst wenn man diesen Lookup umgeht (zum Beispiel indem man den ursprünglichen Pfad aus der Source Map des Bundles rekonstruiert, statt require.cache zu nutzen), gibt es eine zweite, unumgehbare Mauer: Eine von außerhalb des Bundles per require() geladene Docs-Datei erzeugt ein Klassenobjekt, das strukturell anders ist als das, was die laufende App intern tatsächlich verwendet. Diese frische Kopie zu dekorieren hat keinen Effekt auf das Dokument, das SwaggerModule.createDocument() tatsächlich ausliefert. Das passiert lautlos, ohne Fehler.
  • Der einzige Ausweg wäre, dass die Controller-Datei selbst ihre .docs.ts-Companion importiert (womit Webpack gezwungen wäre, beide zusammen zu bündeln) – das untergräbt aber den ganzen Sinn der Konvention: null Kopplung zwischen Controller und Dokumentation.

Wie man trotzdem an vollständige Docs kommt

Das CLI-Plugin (empfohlen): Registriere nestjs-docfy in compilerOptions.plugins von nest-cli.json und ruf applyDocfyMetadata() direkt nach SwaggerModule.createDocument() auf. Behebt das an der Wurzel, automatisch, bei jedem Build. Siehe Das CLI-Plugin.

Use patch-spec als manuelle, CI-gesteuerte Alternative, falls du lieber kein Compiler-Plugin hinzufügen möchtest. Siehe patch-spec: manuelle Alternative. Oder deaktiviere das Webpack-Bundling ganz: entferne "webpack": true (oder setze es auf false) in nest-cli.json. Unter der standardmäßigen tsc-basierten Kompilierung kompiliert jede Quelldatei zu ihrer eigenen .js, sodass require.cache ganz natürlich einen Eintrag pro Datei hat und die Runtime-Discovery von DocfyModule unverändert funktioniert.