338 lines
7.0 KiB
Markdown
338 lines
7.0 KiB
Markdown
这些装饰器是 `@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 文档。
|