pac-auth/docs/swaggerApi.md

这些装饰器是 `@nestjs/swagger` 包提供的一部分，用于增强 Swagger 文档的可读性和完整性。以下是每个装饰器的详细介绍和使用方法：

### @ApiOperation()
- **位置**: 方法
- **用途**: 为 API 操作添加一个简短的描述。

```typescript
@ApiOperation({ summary: '描述这个操作', description: '更详细的描述信息' })
```

### @ApiResponse()
- **位置**: 方法/控制器
- **用途**: 定义一个预期的响应。

```typescript
@ApiResponse({ status: 200, description: '描述响应', type: SomeType })
```

### @ApiProduces()
- **位置**: 方法/控制器
- **用途**: 指定 API 可以返回哪些 MIME 类型。

```typescript
@ApiProduces(['application/json'])
```

### @ApiConsumes()
- **位置**: 方法/控制器
- **用途**: 指定 API 可以接收哪些 MIME 类型。

```typescript
@ApiConsumes(['application/json'])
```

### @ApiBearerAuth()
- **位置**: 方法/控制器
- **用途**: 表示该 API 使用 Bearer Token 进行身份验证。

```typescript
@ApiBearerAuth()
```

### @ApiOAuth2()
- **位置**: 方法/控制器
- **用途**: 表示该 API 使用 OAuth2 进行身份验证，并允许指定授权流程的详细信息。

```typescript
@ApiOAuth2(['read', 'write'])
```

### @ApiBasicAuth()
- **位置**: 方法/控制器
- **用途**: 表示该 API 使用基本认证。

```typescript
@ApiBasicAuth()
```

### @ApiSecurity()
- **位置**: 方法/控制器
- **用途**: 为 API 添加安全定义的引用。

```typescript
@ApiSecurity('APIKey')
```

### @ApiExtraModels()
- **位置**: 方法/控制器
- **用途**: 允许在 Swagger 文档中包含额外的模型，即使它们没有被直接使用。

```typescript
@ApiExtraModels(ExtraModelType)
```

### @ApiBody()
- **位置**: 方法
- **用途**: 描述请求体。

```typescript
@ApiBody({ type: CreateCatDto })
```

### @ApiParam()
- **位置**: 方法
- **用途**: 描述一个路径参数或查询参数。

```typescript
@ApiParam({ name: 'id', required: true })
```

### @ApiQuery()
- **位置**: 方法
- **用途**: 描述一个查询参数。

```typescript
@ApiQuery({ name: 'query', required: false })
```

### @ApiHeader()
- **位置**: 方法/控制器
- **用途**: 描述一个 HTTP 头参数。

```typescript
@ApiHeader({ name: 'X-Custom-Header', required: false })
```

### @ApiExcludeEndpoint()
- **位置**: 方法
- **用途**: 从 Swagger 文档中排除一个特定的端点。

```typescript
@ApiExcludeEndpoint()
```

### @ApiTags()
- **位置**: 方法/控制器
- **用途**: 为 API 端点添加一个或多个标签。

```typescript
@ApiTags('cats')
```

### @ApiProperty()
- **位置**: 模型
- **用途**: 为模型的属性添加元数据。

```typescript
class CatDto {
  @ApiProperty()
  name: string;
}
```

### @ApiPropertyOptional()
- **位置**: 模型
- **用途**: 表示模型属性是可选的。

```typescript
class CatDto {
  @ApiPropertyOptional()
  age?: number;
}
```

### @ApiHideProperty()
- **位置**: 模型
- **用途**: 在 Swagger 文档中隐藏模型的属性。

```typescript
class CatDto {
  @ApiHideProperty()
  privateInfo: string;
}
```

### @ApiExtension()
- **位置**: 模型
- **用途**: 添加自定义的字段到 Swagger 模型定义。

```typescript
class CatDto {
  @ApiExtension('x-omitempty', true)
  @ApiProperty()
  name: string;
}
```

使用这些装饰器，你可以为 NestJS 应用中的每个 API 端点提供丰富的 Swagger 文档，从而帮助开发者更好地理解和使用你的 API。




`@ApiProperty` 装饰器有许多参数，可以用来描述属性的各种信息。以下是常用的参数及其描述：

### 常用参数

1. **description**: 属性的描述。
   ```typescript
   @ApiProperty({ description: 'The username of the user' })
   username: string;
   ```

2. **type**: 属性的数据类型。可以是基本类型、数组或类类型。
   ```typescript
   @ApiProperty({ type: String })
   username: string;
   
   @ApiProperty({ type: [String] })
   roles: string[];
   ```

3. **example**: 属性的示例值。
   ```typescript
   @ApiProperty({ example: 'john_doe' })
   username: string;
   ```

4. **enum**: 属性的枚举值。
   ```typescript
   enum UserRole {
     Admin = 'admin',
     User = 'user',
   }

   @ApiProperty({ enum: UserRole })
   role: UserRole;
   ```

5. **default**: 属性的默认值。
   ```typescript
   @ApiProperty({ default: 'user' })
   role: string;
   ```

6. **required**: 属性是否为必需的（默认为 true）。
   ```typescript
   @ApiProperty({ required: false })
   email?: string;
   ```

7. **format**: 属性的数据格式，例如 `email`, `date-time`, `uuid` 等。
   ```typescript
   @ApiProperty({ format: 'email' })
   email: string;
   ```

8. **minimum**: 数字属性的最小值。
   ```typescript
   @ApiProperty({ minimum: 1 })
   age: number;
   ```

9. **maximum**: 数字属性的最大值。
   ```typescript
   @ApiProperty({ maximum: 100 })
   age: number;
   ```

10. **minLength**: 字符串属性的最小长度。
    ```typescript
    @ApiProperty({ minLength: 5 })
    password: string;
    ```

11. **maxLength**: 字符串属性的最大长度。
    ```typescript
    @ApiProperty({ maxLength: 20 })
    username: string;
    ```

12. **minItems**: 数组属性的最小项目数。
    ```typescript
    @ApiProperty({ minItems: 1 })
    tags: string[];
    ```

13. **maxItems**: 数组属性的最大项目数。
    ```typescript
    @ApiProperty({ maxItems: 10 })
    tags: string[];
    ```

14. **uniqueItems**: 数组项目是否唯一。
    ```typescript
    @ApiProperty({ uniqueItems: true })
    tags: string[];
    ```

15. **pattern**: 字符串属性的正则表达式模式。
    ```typescript
    @ApiProperty({ pattern: '/^[a-z0-9]+$/i' })
    username: string;
    ```

### 示例

以下是一个包含多个 `@ApiProperty` 参数的示例 DTO 类：

```typescript
import { IsString, Length, IsEmail, IsEnum, IsOptional } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

enum UserRole {
  Admin = 'admin',
  User = 'user',
}

export class CreateUserDto {
  @ApiProperty({
    description: 'The username of the user',
    example: 'john_doe',
    minLength: 5,
    maxLength: 20,
    pattern: '^[a-zA-Z0-9]+$',
  })
  @IsString()
  @Length(5, 20)
  username: string;

  @ApiProperty({
    description: 'The password of the user',
    example: 's3cr3t',
    minLength: 8,
  })
  @IsString()
  @Length(8, 50)
  password: string;

  @ApiProperty({
    description: 'The email of the user',
    example: 'john_doe@example.com',
    format: 'email',
  })
  @IsEmail()
  email: string;

  @ApiProperty({
    description: 'The role of the user',
    enum: UserRole,
    example: UserRole.User,
    default: UserRole.User,
  })
  @IsEnum(UserRole)
  role: UserRole;

  @ApiProperty({
    description: 'The tags associated with the user',
    type: [String],
    example: ['admin', 'user'],
    required: false,
  })
  @IsOptional()
  tags?: string[];
}
```

通过配置这些参数，可以为属性提供丰富的元数据，从而生成更详细的 Swagger 文档。