pac-auth

7.0 KiB

Raw Blame History

这些装饰器是 @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 文档。

7.0 KiB Raw Blame History