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));

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.