You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
337 lines
7.0 KiB
337 lines
7.0 KiB
这些装饰器是 `@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 文档。
|
|
|