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.
7.0 KiB
7.0 KiB
这些装饰器是 @nestjs/swagger
包提供的一部分,用于增强 Swagger 文档的可读性和完整性。以下是每个装饰器的详细介绍和使用方法:
@ApiOperation()
- 位置: 方法
- 用途: 为 API 操作添加一个简短的描述。
@ApiOperation({ summary: '描述这个操作', description: '更详细的描述信息' })
@ApiResponse()
- 位置: 方法/控制器
- 用途: 定义一个预期的响应。
@ApiResponse({ status: 200, description: '描述响应', type: SomeType })
@ApiProduces()
- 位置: 方法/控制器
- 用途: 指定 API 可以返回哪些 MIME 类型。
@ApiProduces(['application/json'])
@ApiConsumes()
- 位置: 方法/控制器
- 用途: 指定 API 可以接收哪些 MIME 类型。
@ApiConsumes(['application/json'])
@ApiBearerAuth()
- 位置: 方法/控制器
- 用途: 表示该 API 使用 Bearer Token 进行身份验证。
@ApiBearerAuth()
@ApiOAuth2()
- 位置: 方法/控制器
- 用途: 表示该 API 使用 OAuth2 进行身份验证,并允许指定授权流程的详细信息。
@ApiOAuth2(['read', 'write'])
@ApiBasicAuth()
- 位置: 方法/控制器
- 用途: 表示该 API 使用基本认证。
@ApiBasicAuth()
@ApiSecurity()
- 位置: 方法/控制器
- 用途: 为 API 添加安全定义的引用。
@ApiSecurity('APIKey')
@ApiExtraModels()
- 位置: 方法/控制器
- 用途: 允许在 Swagger 文档中包含额外的模型,即使它们没有被直接使用。
@ApiExtraModels(ExtraModelType)
@ApiBody()
- 位置: 方法
- 用途: 描述请求体。
@ApiBody({ type: CreateCatDto })
@ApiParam()
- 位置: 方法
- 用途: 描述一个路径参数或查询参数。
@ApiParam({ name: 'id', required: true })
@ApiQuery()
- 位置: 方法
- 用途: 描述一个查询参数。
@ApiQuery({ name: 'query', required: false })
@ApiHeader()
- 位置: 方法/控制器
- 用途: 描述一个 HTTP 头参数。
@ApiHeader({ name: 'X-Custom-Header', required: false })
@ApiExcludeEndpoint()
- 位置: 方法
- 用途: 从 Swagger 文档中排除一个特定的端点。
@ApiExcludeEndpoint()
@ApiTags()
- 位置: 方法/控制器
- 用途: 为 API 端点添加一个或多个标签。
@ApiTags('cats')
@ApiProperty()
- 位置: 模型
- 用途: 为模型的属性添加元数据。
class CatDto {
@ApiProperty()
name: string;
}
@ApiPropertyOptional()
- 位置: 模型
- 用途: 表示模型属性是可选的。
class CatDto {
@ApiPropertyOptional()
age?: number;
}
@ApiHideProperty()
- 位置: 模型
- 用途: 在 Swagger 文档中隐藏模型的属性。
class CatDto {
@ApiHideProperty()
privateInfo: string;
}
@ApiExtension()
- 位置: 模型
- 用途: 添加自定义的字段到 Swagger 模型定义。
class CatDto {
@ApiExtension('x-omitempty', true)
@ApiProperty()
name: string;
}
使用这些装饰器,你可以为 NestJS 应用中的每个 API 端点提供丰富的 Swagger 文档,从而帮助开发者更好地理解和使用你的 API。
@ApiProperty
装饰器有许多参数,可以用来描述属性的各种信息。以下是常用的参数及其描述:
常用参数
-
description: 属性的描述。
@ApiProperty({ description: 'The username of the user' }) username: string;
-
type: 属性的数据类型。可以是基本类型、数组或类类型。
@ApiProperty({ type: String }) username: string; @ApiProperty({ type: [String] }) roles: string[];
-
example: 属性的示例值。
@ApiProperty({ example: 'john_doe' }) username: string;
-
enum: 属性的枚举值。
enum UserRole { Admin = 'admin', User = 'user', } @ApiProperty({ enum: UserRole }) role: UserRole;
-
default: 属性的默认值。
@ApiProperty({ default: 'user' }) role: string;
-
required: 属性是否为必需的(默认为 true)。
@ApiProperty({ required: false }) email?: string;
-
format: 属性的数据格式,例如
email
,date-time
,uuid
等。@ApiProperty({ format: 'email' }) email: string;
-
minimum: 数字属性的最小值。
@ApiProperty({ minimum: 1 }) age: number;
-
maximum: 数字属性的最大值。
@ApiProperty({ maximum: 100 }) age: number;
-
minLength: 字符串属性的最小长度。
@ApiProperty({ minLength: 5 }) password: string;
-
maxLength: 字符串属性的最大长度。
@ApiProperty({ maxLength: 20 }) username: string;
-
minItems: 数组属性的最小项目数。
@ApiProperty({ minItems: 1 }) tags: string[];
-
maxItems: 数组属性的最大项目数。
@ApiProperty({ maxItems: 10 }) tags: string[];
-
uniqueItems: 数组项目是否唯一。
@ApiProperty({ uniqueItems: true }) tags: string[];
-
pattern: 字符串属性的正则表达式模式。
@ApiProperty({ pattern: '/^[a-z0-9]+$/i' }) username: string;
示例
以下是一个包含多个 @ApiProperty
参数的示例 DTO 类:
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 文档。