De CLI-plugin

De aanbevolen fix voor webpack: true, automatisch, bij elke build, zonder losse stap om te onthouden.

Dit is hetzelfde mechanisme dat de eigen CLI-plugin van @nestjs/swagger gebruikt om onder webpack: true te werken. Daarom is @ApiProperty() niet vereist op elke DTO-property, zelfs niet in een webpack-build. De Nest CLI voedt een TypeScript-compilerplugin-hook (compilerOptions.plugins) identiek naar zowel de tsc</4- als de webpack-builder (ts-loader).

Registreer de plugin

Registreer nestjs-docfy in nest-cli.json:

nest-cli.json
{
  "compilerOptions": {
    "webpack": true,
    "plugins": ["nestjs-docfy"]
  }
}
main.ts
import { applyDocfyMetadata } from 'nestjs-docfy';

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, applyDocfyMetadata(document));
OptionTypeDefaultDescription
metadataPathstringdocfy-metadata.json next to the running entry fileWhere to read the plugin-generated metadata from.
strictbooleanfalseThrow instead of warning when the metadata file is missing or invalid.

Automatische detectie

De plugin vergeten te registreren is makkelijk over het hoofd te zien tot een build zonder documentatie uitgaat, dus checkt elke generate-run al nest-cli.json en print een waarschuwing wanneer webpack: true staat zonder de plugin. Geef --register-plugin mee om dat automatisch te laten repareren in plaats van het bestand met de hand te bewerken:

bash
npx nestjs-docfy generate --register-plugin

Dit is bewust opt-in, want sommige teams houden bewust vast aan patch-spec in plaats van een compilerplugin, dus bewerkt generate nest-cli.json nooit tenzij je daar expliciet om vraagt. Het voegt toe aan een bestaande compilerOptions.plugins-array (herkent zowel string- als objectvorm-entries als al geregistreerd) en respecteert --dry-run.

Hoe het werkt

De plugin van nestjs-docfy herschrijft geen decoratorsyntax en raakt de AST helemaal niet aan. Bij elke compilatie draait ze exact dezelfde statische analyse die generate/check/patch-spec al doen (via ts-morph, tegen de bronboom, niet de bundel) en schrijft ze de resulterende patch naar docfy-metadata.json naast de build-output.

Daarna, meteen na SwaggerModule.createDocument(), leest applyDocfyMetadata() dat bestand en voegt het samen. Er komt geen require.cache bij kijken en geen probleem met gebundelde class-identiteit, want het heeft de draaiende app nooit nodig om iets te berekenen.

vs. patch-spec

Manual, CI-driven alternative

Wil je liever geen compilerplugin toevoegen (bijvoorbeeld een build-pijplijn die niet de Nest CLI is, of een strikter beleid over wat er tijdens compilatie draait), dan berekent patch-spec dezelfde patch handmatig tegen een al gebouwd document. Dat was de enige optie voordat de plugin bestond, en blijft nuttig voor eenmalige patches.