## 類型和參數 `SwaggerModule`在路徑處理程序上搜索所有`@Body()`, `@Query()`, 以及`@Param()`裝飾器來生成API文檔。它也利用反射來創建響應模型。考慮以下代碼： ```TypeScript @Post() async create(@Body() createCatDto: CreateCatDto) { this.catsService.create(createCatDto); } ``` > 要顯式定義主體，使用`@ApiBody()`裝飾器 (從`@nestjs/swagger`引入). 基于`CreateCatDto`,將創建以下Swagger頁面模型。  如你所見，雖然類已經聲明了一些屬性，但這里的定義是空的。要使這些類屬性在`SwaggerModule`中可見，我們要么用`@ApiProperty()`裝飾器或使用`CLI`插件來自動生成： ```TypeScript import { ApiProperty } from '@nestjs/swagger'; export class CreateCatDto { @ApiProperty() name: string; @ApiProperty() age: number; @ApiProperty() breed: string; } ``` > 考慮使用Swagger插件（參見[CLI插件](#CLI插件)）來自動生成以代替手動裝飾每個屬性。 打開瀏覽器確認生成的`CreateCatDto`模型:  `@ApiProperty()`裝飾器也允許設置不同的原型對象屬性: ```TypeScript @ApiProperty({ description: 'The age of a cat', minimum: 1, default: 1, }) age: number; ``` > 可以使用`@ApiPropertyOptional()`速記裝飾器來替代顯式輸入`@ApiProperty({ required: false })`。 要顯式指定屬性類型，使用`type`字段： ```TypeScript @ApiProperty({ type: Number, }) age: number; ``` ### 數組 當屬性是數組時，我們必須手動指定數組類型： ```TypeScript @ApiProperty({ type: [String] }) names: string[]; ``` > 考慮使用Swagger 插件來自動發現數組 要么將類型作為數組的第一個元素（如上），要么將`isArray`屬性設為`true`。 ### 循環依賴 當你的類之間有循環依賴時，使用`SwaggerModul`提供的一個包含類型信息的懶函數。 ```TypeScript @ApiProperty({ type: () => Node }) node: Node; ``` > 考慮使用Swagger 插件來自動發現循環依賴 ### 泛型和接口 由于`TypeScript`沒有存儲泛型或者接口的元數據，當你在DTO中使用他們的時候，`SwaggerModule`可能不會正確生成運行時的模型定義。基于此，下列代碼不會被Swagger模塊正確識別。 ```TypeScript createBulk(@Body() usersDto: CreateUserDto[]) ``` 要處理這些限制，需要顯式配置類型： ```TypeScript @ApiBody({ type: [CreateUserDto] }) createBulk(@Body() usersDto: CreateUserDto[]) ``` ### 枚舉 要定義一個枚舉，需要在`@ApiProperty`中用數組手動設置`enum`屬性。 ```TypeScript @ApiProperty({ enum: ['Admin', 'Moderator', 'User']}) role: UserRole; ``` 也可以如下定義一個真實的`TypeScript`泛型： ```TypeScript export enum UserRole { Admin = 'Admin', Moderator = 'Moderator', User = 'User', } ``` 可以在`@Query()`參數中配合`@ApiQuery()`裝飾器直接使用`enum`： ```TypeScript @ApiQuery({ name: 'role', enum: UserRole }) async filterByRole(@Query('role') role: UserRole = UserRole.User) {} ```  當`isArray`配置為`true`時, `enum`可以多選。  ### 枚舉原型 默認地，`enum`屬性將為[Enum](https://swagger.io/docs/specification/data-models/enums/)在`parameter`上添加一個原始定義。 ```TypeScript - breed: type: 'string' enum: - Persian - Tabby - Siamese ``` 上述定義在大部分情況下工作良好。然而，如果你使用該定義作為輸入在客戶端生成代碼時，可能會遇到屬性包含重復枚舉的情況，考慮以下代碼： ```TypeScript // generated client-side code export class CatDetail { breed: CatDetailEnum; } export class CatInformation { breed: CatInformationEnum; } export enum CatDetailEnum { Persian = 'Persian', Tabby = 'Tabby', Siamese = 'Siamese', } export enum CatInformationEnum { Persian = 'Persian', Tabby = 'Tabby', Siamese = 'Siamese', } ``` > 上述代碼使用[NSwag](https://github.com/RicoSuter/NSwag)工具生成 現在可以看到有兩個枚舉完全一樣，要處理這個問題，需要在裝飾器的`enum`屬性中傳入`enumName`參數。 ```TypeScript export class CatDetail { @ApiProperty({ enum: CatBreed, enumName: 'CatBreed' }) breed: CatBreed; } ``` `enumName`屬性使能`@nestjs/swagger`來將`CatBreed`轉換為其原型，從而使`CatBreed`可重用： ```TypeScript CatDetail: type: 'object' properties: ... - breed: schema: $ref: '#/components/schemas/CatBreed' CatBreed: type: string enum: - Persian - Tabby - Siamese ``` > 任何包含`enum`屬性的裝飾器都有`enumName` ### 原始定義 在一些特殊場合(例如深度嵌套的數組和矩陣),你可能需要手動描述你的類型。 ```TypeScript @ApiProperty({ type: 'array', items: { type: 'array', items: { type: 'number', }, }, }) coords: number[][]; ``` 類似地，要在控制器類中手動定義輸入輸出，使用`schema`屬性: ```TypeScript @ApiBody({ schema: { type: 'array', items: { type: 'array', items: { type: 'number', }, }, }, }) async create(@Body() coords: number[][]) {} ``` ### 額外模型 要定義控制器中沒有直接使用，但是需要被Swagger模塊檢查的額外的模型，使用`@ApiExtraModels()`裝飾器: ```TypeScript @ApiExtraModels(ExtraModel) export class CreateCatDto {} ``` > 只需要對指定的model類使用一次`@ApiExtraModels()` 你也可以把一個選項對象和`extraModels`屬性一起傳遞給`SwaggerModule#createDocument()` 方法： ```TypeScript const document = SwaggerModule.createDocument(app, options, { extraModels: [ExtraModel], }); ``` 要獲得一個模型的引用(`$ref`) ,使用`getSchemaPath(ExtraModel)`函數: ```TypeScript 'application/vnd.api+json': { schema: { $ref: getSchemaPath(ExtraModel) }, }, ``` ### `oneOf`, `anyOf`, `allOf` 要組合原型，你可以使用`oneOf`,`anyOf` 或者`allOf`關鍵詞([閱讀更多](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/)). ```TypeScript @ApiProperty({ oneOf: [ { $ref: getSchemaPath(Cat) }, { $ref: getSchemaPath(Dog) }, ], }) pet: Cat | Dog; ``` 如果你要定義一個多態數組（例如，數組成員跨越多個原型），你應該使用前節的原始定義來手動定義你的類型。 ```TypeScript type Pet = Cat | Dog; @ApiProperty({ type: 'array', items: { oneOf: [ { $ref: getSchemaPath(Cat) }, { $ref: getSchemaPath(Dog) }, ], }, }) pets: Pet[]; ``` > `getSchemaPath()`函數從`@nestjs/swagger`引入. `Cat`和`Dog`都應該使用`@ApiExtraModels()`裝飾器 (在類水平).