strict mode & webpack

Twee instellingen die het gedrag bij het opstarten bepalen: de ene voor CI, de andere over een architecturale beperking.

strict: true

Geef { strict: true } mee aan forRoot() zodat de app bij het opstarten een fout gooit wanneer een controller met @WithDocs() geen companion-bestand heeft. Aanbevolen voor CI, waar snel falen te verkiezen is boven een stilletjes onvolledig OpenAPI-document.

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

webpack: true

De runtime discovery van DocfyModule werkt hier niet

Heeft je nest-cli.json "webpack": true onder compilerOptions staan, dan werkt de runtime-pijplijn van DocfyModule (de @WithDocs() + require.cache discovery hierboven beschreven) niet, en geen enkele configuratie verandert daar iets aan. Dit is architecturaal, en heeft twee oorzaken:

Ten eerste bundelt webpack elke module in één bundelbestand en vult het nooit Node's require.cache met één entry per origineel bronbestand, waar het discovery-mechanisme van afhankelijk is. Je ziet Could not locate source file for X voor elke controller met @WithDocs().

Ten tweede, zelfs als je die lookup omzeilt, 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 applicatie intern daadwerkelijk gebruikt. Dat geïsoleerde exemplaar decoreren heeft geen enkel effect op het document dat SwaggerModule.createDocument() daadwerkelijk serveert, en dat gebeurt stilletjes, zonder foutmelding.

Twee manieren om toch volledige docs te krijgen, in volgorde van voorkeur:

  • De CLI-plugin (aanbevolen): repareert dit bij de bron, automatisch, bij elke build, met hetzelfde mechanisme dat de eigen CLI-plugin van @nestjs/swagger gebruikt. Zie De CLI-plugin.
  • Use patch-spec: een handmatige, CI-gedreven statische patch van een al gebouwd OpenAPI-document, zonder afhankelijkheid van require.cache. Zie CLI: patch-spec en patch-spec: handmatig alternatief.