Le plugin CLI

Le correctif recommandé pour webpack: true, automatique, à chaque build, sans étape séparée à retenir.

C'est le même mécanisme que le plugin CLI de @nestjs/swagger lui-même utilise pour fonctionner sous webpack: true. C'est pour ça que @ApiProperty() n'est pas requis sur chaque propriété de DTO même dans un build webpack. Le CLI Nest alimente un hook de plugin compilateur TypeScript (compilerOptions.plugins) de façon identique dans le builder tsc et dans le builder webpack (ts-loader).

Enregistrer le plugin

Enregistre nestjs-docfy dans 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.

Détection automatique

Oublier d'enregistrer le plugin est facile à manquer jusqu'à ce qu'un build parte sans documentation, donc chaque exécution de generate vérifie déjà nest-cli.json et affiche un avertissement quand webpack: true est activé sans le plugin. Passe --register-plugin pour que ça soit corrigé automatiquement au lieu de modifier le fichier à la main :

bash
npx nestjs-docfy generate --register-plugin

C'est volontairement opt-in, puisque certaines équipes préfèrent délibérément s'en tenir à patch-spec plutôt qu'à un plugin de compilateur, donc generate ne modifie jamais nest-cli.json sauf si tu le demandes explicitement. Ça ajoute à tout tableau compilerOptions.plugins existant (en reconnaissant les entrées sous forme de chaîne comme d'objet comme déjà enregistrées) et respecte --dry-run.

Comment ça marche

Le plugin de nestjs-docfy ne réécrit aucune syntaxe de décorateur et ne touche pas du tout à l'AST. À chaque compilation, il relance exactement la même analyse statique que generate/check/patch-spec font déjà (via ts-morph, contre l'arbre source, pas le bundle) et écrit le patch résultant dans docfy-metadata.json à côté de la sortie de build.

Ensuite, juste après SwaggerModule.createDocument(), applyDocfyMetadata() lit ce fichier et le fusionne. Il n'y a aucune implication de require.cache et aucun problème d'identité de classe bundlée, parce que ça n'a jamais besoin de l'app en cours d'exécution pour calculer quoi que ce soit.

vs. patch-spec

Manual, CI-driven alternative

Si tu préfères ne pas ajouter de plugin de compilateur (par exemple, un pipeline de build qui n'est pas le CLI Nest, ou une politique plus stricte sur ce qui s'exécute pendant la compilation), patch-spec calcule le patch identique à la main contre un document déjà construit. C'était la seule option avant l'existence du plugin, et ça reste utile pour un patch ponctuel.

Builder SWC

@nestjs/cli traite le builder SWC différemment. Il n'appelle jamais before() sous "builder": "swc", seulement un ReadonlyVisitor, et seulement quand "typeCheck": true est aussi activé (sinon SWC saute la vérification de types de lui-même). Ce plugin exporte les deux hooks, donc activer ce réglage suffit :

nest-cli.json
{
  "compilerOptions": {
    "builder": "swc",
    "typeCheck": true,
    "plugins": ["nestjs-docfy"]
  }
}
Requires typeCheck: true

Une chose à savoir : enregistrer le plugin de cette façon écrit un fichier metadata.ts à côté de la racine de ton source à chaque build. C'est le même artefact que le support SWC de @nestjs/swagger produit déjà là, vide et inoffensif si ce plugin n'est pas aussi enregistré.

Omets typeCheck et le plugin devient silencieux à la place. Le build continue de réussir, mais aucun docfy-metadata.json n'est écrit et applyDocfyMetadata() n'a rien à fusionner. generate détecte exactement cette combinaison et prévient.

Rien de tout ça ne touche à la découverte runtime de DocfyModule. Elle fonctionne sous SWC exactement comme sous tsc, puisque SWC compile toujours un fichier par module et que require.cache finit peuplé de la même façon. Si activer typeCheck n'est pas une option, @WithDocs() avec DocfyModule.forRoot() t'y amène quand même, sans le plugin.