Bestandsnaamconventie

Discovery is automatisch. DocfyModule lokaliseert het bronbestand van elke controller via Node's module cache.

Conventie

Discovery is automatisch. DocfyModule lokaliseert het bronbestand van elke controller via Node's module cache en lost het companion-pad op: dit werkt identiek onder ts-node (development) en gecompileerde dist/ (productie).

ControllerbestandCompanion-bestand
users.controller.tsusers.controller.docs.ts
users.controller.jsusers.controller.docs.js

Barrel re-exports

Barrel re-exports

Wordt je controller ook geëxporteerd vanuit een barrel index.ts, zorg er dan voor dat de klasse rechtstreeks vanuit zijn eigen modulebestand geëxporteerd wordt. nestjs-docfy geeft de voorkeur aan .controller.ts boven barrel-bestanden.

webpack: true build-modus

Heeft je nest-cli.json "webpack": true onder compilerOptions staan (de gedocumenteerde standaard voor monorepo's met meerdere apps), dan werkt de runtime-pijplijn van DocfyModule (de hierboven beschreven @WithDocs() + require.cache discovery) niet, en geen enkele configuratie verandert daar iets aan. Dit is architecturaal:

  • Webpack inlinet elke module in één bundelbestand en vult Node's require.cache nooit met één entry per origineel bronbestand, waar het discovery-mechanisme van afhangt. Je ziet Could not locate source file for X voor elke controller met @WithDocs().
  • Zelfs als die lookup omzeild wordt (bijvoorbeeld door het originele pad terug te halen uit de source map van de bundel, require.cache overslaand), is er een tweede, onvermijdelijke muur: een docsbestand dat via require() van buiten de bundel geladen wordt, creëert een classobject dat structureel anders is dan het object dat de draaiende app intern daadwerkelijk gebruikt. Dat verse exemplaar decoreren heeft geen effect op het document dat SwaggerModule.createDocument() daadwerkelijk serveert. Dat gebeurt stilletjes, zonder foutmelding.
  • De enige manier hieromheen zou zijn dat het controllerbestand zelf zijn .docs.ts-companion importeert (waardoor webpack gedwongen wordt beide samen te bundelen), wat het hele punt van de conventie tenietdoet: geen koppeling tussen controller en documentatie.

Hoe je toch volledige docs krijgt

De CLI-plugin (aanbevolen): registreer nestjs-docfy in compilerOptions.plugins van nest-cli.json en roep applyDocfyMetadata() aan meteen na SwaggerModule.createDocument(). Repareert dit bij de bron, automatisch, bij elke build. Zie De CLI-plugin.

Use patch-spec als handmatig, CI-gedreven alternatief als je liever geen compilerplugin toevoegt. Zie patch-spec: handmatig alternatief. Of schakel webpack-bundeling helemaal uit: verwijder "webpack": true (of zet het op false) in nest-cli.json. Onder de standaard tsc-gebaseerde compilatie compileert elk bronbestand naar zijn eigen .js, dus heeft require.cache van nature één entry per bestand en werkt de runtime discovery van DocfyModule ongewijzigd.