## CLI插件 TypeScript的元數據反射系統有一些限制，一些功能因此不可能實現，例如確定一個類由哪些屬性組成，或者一個屬性是可選的還是必須的。然而，一些限制可以在編譯時強調。Nest提供了一個增強TypeScript編譯過程的插件來減少需要的原型代碼量。 > 這個插件是一個`可選的`，你也可以選擇手動聲明所有的裝飾器，或者僅僅聲明你需要的。 ### 概述 Swagger插件可以自動： - 使用`@ApiProperty`注釋所有除了用`@ApiHideProperty`裝飾的DTO屬性。 - 根據問號符號確定`required`屬性(例如 `name?: string` 將設置`required: false`) - 根據類型配置`type`為`enum`(也支持數組) - 基于給定的默認值配置默認參數 - 基于`class-validator`裝飾器配置一些驗證策略(如果`classValidatorShim`配置為`true`) - 為每個終端添加一個響應裝飾器，包括合適的狀態和類型（響應模式） - 根據注釋生成屬性和終端的描述(如果`introspectComments`配置為`true`) - 基于注釋生成屬性的示例數據(如果`introspectComments`配置為`true`) 注意，你的文件名必須有如下后綴: `['.dto.ts', '.entity.ts']` (例如`create-user.dto.ts`) 才能被插件分析。 如果使用其他后綴，你可以調整插件屬性來指定`dtoFileNameSuffix`選項(見下文)。 之前，如果你想要通過Swagger提供一個交互體驗，你必須復制大量代碼讓包知道你的模型/組件在該聲明中。例如，你可以定義一個`CreateUserDto`類: ```TypeScript export class CreateUserDto { @ApiProperty() email: string; @ApiProperty() password: string; @ApiProperty({ enum: RoleEnum, default: [], isArray: true }) roles: RoleEnum[] = []; @ApiProperty({ required: false, default: true }) isEnabled?: boolean = true; } ``` 在中等項目中這還不是問題，但是一旦有大量類的話這就變得冗余而難以維護。 要應用Swagger插件，可以簡單聲明上述類定義： ```TypeScript export class CreateUserDto { email: string; password: string; roles: RoleEnum[] = []; isEnabled?: boolean = true; } ``` 插件可以通過抽象語法樹添加合適的裝飾器，你不在需要在代碼中到處寫`ApiProperty`裝飾器。 > 插件可以自動生成所有缺失的swagger屬性，但是如果你要覆蓋他們，只需要通過`@ApiProperty()`顯式聲明即可。 ### 注釋自省 注釋自省特性使能后，CLI插件可以基于注釋生成描述和示例值。 例如，一個給定的`roles`屬性示例： ```TypeScript /** * A list of user's roles * @example ['admin'] */ @ApiProperty({ description: `A list of user's roles`, example: ['admin'], }) roles: RoleEnum[] = []; ``` 你必須復制描述和示例值。當`introspectComments`使能后，CLI插件可以自動解壓這些注釋并提供描述（以及示例，如果定義了的話）。現在，上述屬性可以簡化為： ```TypeScript /** * A list of user's roles * @example ['admin'] */ roles: RoleEnum[] = []; ``` ### 使用CLI插件 要使能CLI插件，打開`nest-cli.json` (如果你在用[Nest CLI](https://docs.nestjs.com/cli/overview))并添加以下插件配置： ```TypeScript { "collection": "@nestjs/schematics", "sourceRoot": "src", "compilerOptions": { "plugins": ["@nestjs/swagger"] } } ``` 你可以使用其他`options`屬性來自定義插件特性。 ```TypeScript "plugins": [ { "name": "@nestjs/swagger", "options": { "classValidatorShim": false, "introspectComments": true } } ] ``` `options`屬性實現以下接口： ```TypeScript export interface PluginOptions { dtoFileNameSuffix?: string[]; controllerFileNameSuffix?: string[]; classValidatorShim?: boolean; introspectComments?: boolean; } ``` 選項|默認|說明 ---|---|--- dtoFileNameSuffix|['.dto.ts', '.entity.ts']|DTO (數據傳輸對象)文件后綴 controllerFileNameSuffix|.controller.ts|控制文件后綴 classValidatorShim|true|如果配置為`true`，模塊將重用`class-validator`驗證裝飾器 (例如`@Max(10) `將在`schema`定義中增加`max: 10`) introspectComments|false|如果配置為`true`,插件將根據描述注釋生成說明和示例 如果不使用CLI，但是使用一個用戶定義的`Webpack`配置，可以和`ts-loader`配合使用該插件： ```TypeScript getCustomTransformers: (program: any) => ({ before: [require('@nestjs/swagger/plugin').before({}, program)] }), ``` ### `ts-jest`與（e2e 測試）集成 要運行e2e測試，`ts-jest`在內存匯總編譯源碼，這意味著不使用Nest Cli編譯，不應用任何插件或AST轉換，要使用插件，在e2e測試目錄下創建以下文件： ```TypeScript const transformer = require('@nestjs/swagger/plugin'); module.exports.name = 'nestjs-swagger-transformer'; // you should change the version number anytime you change the configuration below - otherwise, jest will not detect changes module.exports.version = 1; module.exports.factory = (cs) => { return transformer.before( { // @nestjs/swagger/plugin options (can be empty) }, cs.tsCompiler.program, ); }; ``` 在jest配置文件中引入AST變換。默認在（啟動應用中），e2e測試配置文件在測試目錄下，名為`jest-e2e.json`。 ```TypeScript { ... // other configuration "globals": { "ts-jest": { "astTransformers": { "before": ["<path to the file created above>"], } } } } ``` #### 故障排除`jest`（e2e 測試） 如果`jest` 似乎沒有接收到您的配置更改，則 Jest 可能已經\*\*緩存\*\*了構建結果。要應用新配置，您需要清除 Jest 的緩存目錄。 要清除緩存目錄，請在 NestJS 項目文件夾中運行以下命令： ~~~bash $ npx jest --clearCache ~~~ 如果自動清除緩存失敗，您仍然可以使用以下命令手動刪除緩存文件夾： ~~~bash # 查找 jest 緩存目錄 (通常是 /tmp/jest_rs) # 通過在您的 NestJS 項目根目錄中運行以下命令 $ npx jest --showConfig | grep cache # ex result: # "cache": true, # "cacheDirectory": "/tmp/jest_rs" # Remove or empty the Jest cache directory $ rm -rf <cacheDirectory value> # ex: # rm -rf /tmp/jest_rs ~~~