CLI Plugin - Le Scribe automatique

Imagine que dans la chancellerie impériale tu disposes d'un scribe qui documente automatiquement chaque décret à partir de son contenu - tu n'as pas besoin de lui dire quoi écrire, il comprend seul la structure du document. C'est exactement ainsi que fonctionne le CLI Plugin de @nestjs/swagger.

Le problème de la documentation manuelle

Sans le CLI Plugin, tu dois ajouter manuellement @ApiProperty() à chaque champ de chaque DTO :

1// Sans CLI Plugin - beaucoup de code répétitif
2export class CreateLegionaryDto {
3  @ApiProperty({ description: 'Name of the legionary' })
4  name: string;
5
6  @ApiProperty({ description: 'Rank', required: false })
7  rank?: string;
8
9  @ApiProperty({ description: 'Experience' })
10  experience: number;
11
12  @ApiProperty({ description: 'Is active' })
13  isActive: boolean;
14}

CLI Plugin - Génération automatique

Le CLI Plugin analyse les types TypeScript et génère automatiquement les métadonnées Swagger. Une simple classe suffit :

1// Avec CLI Plugin - code propre, documentation automatique
2export class CreateLegionaryDto {
3  /** Name of the legionary */
4  name: string;
5
6  /** Rank in the legion */
7  rank?: string;
8
9  /** Years of experience */
10  experience: number;
11
12  /** Whether the legionary is active */
13  isActive: boolean;
14}

Le plugin, automatiquement :

• Reconnaît les types de champs (string, number, boolean)
• Marque les champs avec ? comme optionnels
• Convertit les commentaires JSDoc en descriptions Swagger
• Génère les @ApiProperty() appropriés au moment de la compilation

Configuration dans nest-cli.json

Pour activer le CLI Plugin, ajoute la configuration appropriée dans le fichier nest-cli.json :

1{
2  "collection": "@nestjs/schematics",
3  "sourceRoot": "src",
4  "compilerOptions": {
5    "deleteOutDir": true,
6    "plugins": [
7      {
8        "name": "@nestjs/swagger",
9        "options": {
10          "classValidatorShim": true,
11          "introspectComments": true,
12          "dtoFileNameSuffix": [".dto.ts", ".entity.ts"]
13        }
14      }
15    ]
16  }
17}

Options du CLI Plugin

introspectComments - Commentaires comme documentation

Lorsque introspectComments est activé, les commentaires JSDoc deviennent des descriptions Swagger :

1export class LegionDto {
2  /**
3   * Unique legion name in the Empire
4   * @example 'Legio X Gemina'
5   */
6  name: string;
7
8  /**
9   * Stationing province
10   * @example 'Pannonia'
11   */
12  province: string;
13
14  /**
15   * Number of soldiers in the legion
16   * @example 5000
17   */
18  soldiers: number;
19}

La balise @example génère automatiquement une valeur d'exemple dans Swagger UI.

classValidatorShim - Intégration avec la validation

Lorsque classValidatorShim est activé, les décorateurs class-validator influencent la documentation Swagger :

1import { IsString, IsNumber, IsOptional, Min, Max, IsEnum } from 'class-validator';
2
3export class CreateLegionaryDto {
4  /** Name of the legionary */
5  @IsString()
6  name: string;
7
8  /** Rank in the legion */
9  @IsEnum(LegionaryRank)
10  @IsOptional()
11  rank?: LegionaryRank;
12
13  /** Years of experience */
14  @IsNumber()
15  @Min(0)
16  @Max(40)
17  experience: number;
18}

Le plugin, automatiquement :

• @IsOptional() marque le champ comme required: false
• @IsEnum() génère la liste des valeurs autorisées
• @Min() / @Max() définit minimum / maximum
• @IsString() confirme le type string

Quand utiliser encore @ApiProperty ?

Le CLI Plugin ne remplace pas tous les cas d'usage de @ApiProperty(). Tu en as encore besoin pour :

• Les types imbriqués (type: () => AddressDto)
• Les tableaux d'objets (type: [LegionaryDto])
• Les exemples complexes
• Remplacer les descriptions générées automatiquement

Exercice pratique

Configure le CLI Plugin et crée un DTO avec des commentaires JSDoc :

1// Configuration du CLI Plugin @nestjs/swagger
2// Ce fichier présente la configuration de nest-cli.json
3
4const nestCliConfig = {
5  collection: "@nestjs/schematics",
6  sourceRoot: "src",
7  compilerOptions: {
8    deleteOutDir: true,
9    plugins: [
10      {
11        name: "@nestjs/swagger",
12        options: {
13          // TODO: Active classValidatorShim (true)
14          // TODO: Active introspectComments (true)
15          // TODO: Définis dtoFileNameSuffix à ['.dto.ts', '.entity.ts']
16        }
17      }
18    ]
19  }
20};
21
22console.log("=== nest-cli.json config ===");
23console.log(JSON.stringify(nestCliConfig, null, 2));
24
25// Exemple de DTO avec des commentaires JSDoc (au lieu de @ApiProperty)
26class LegionaryDto {
27  /** Nom unique du légionnaire
28   * @example 'Marcus Aurelius'
29   */
30  name: string;
31
32  /** Rang dans la hiérarchie de la légion
33   * @example 'Centurio'
34   */
35  rank?: string;
36
37  /** Années de service dans la légion
38   * @example 8
39   */
40  experience: number;
41
42  /** Whether the legionary is active in service
43   * @example true
44   */
45  isActive: boolean;
46}
47
48console.log("");
49console.log("Avec le CLI Plugin, les commentaires JSDoc deviennent des descriptions Swagger");
50console.log("La balise @example génère des valeurs d'exemple");
51console.log("Les champs avec ? sont automatiquement marqués comme optionnels");
52console.log("classValidatorShim intègre la validation à la documentation");
53