详解JAVA中的@Schema注解

前言

由于更换新项目，最初看到@Schema注解还有些疑问，此处专门补充这方面的知识

对于Java的相关知识推荐阅读：java框架 零基础从入门到精通的学习路线 附开源项目面经等（超全）

1. 基本知识

在 Swagger 3 中，引入了 @Schema 注解来描述数据模型，用于取代 Swagger 2 中的 @ApiModelProperty

与 Swagger 2 不同，Swagger 3 使用 @Schema 注解来描述整个数据模型，包括类和属性，使得描述更加一致和清晰

对于swagger2的注解，可看这篇文章补充：
详解JAVA中的@ApiModel和@ApiModelProperty注解

具体代码示例如下：

@Schema(description = "User information")
public class User {
    @Schema(description = "User's unique identifier")
    private Long id;
    
    @Schema(description = "User's name")
    private String name;
    
    // Getters and setters
}

实战代码示例如下：

@Schema(description = "管理后台 - 充值套餐 Response VO")
@Data
@EqualsAndHashCode(callSuper = true)
@ToString(callSuper = true)
public class WalletRechargePackageRespVO extends WalletRechargePackageBaseVO {

    @Schema(description = "编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "9032")
    private Long id;

    @Schema(description = "创建时间", requiredMode = Schema.RequiredMode.REQUIRED)
    private LocalDateTime createTime;

}

相应的属性介绍如下：

• requiredMode：指定该属性的必需性
  Schema.RequiredMode.REQUIRED 表示这个属性是必需
• example：提供该属性的示例值
  展示该属性的一个具体示例

2. 差异

针对swagger2的注解比较

以下是注解的升级过程

注解	swagger2	swagger3
@Api → @Tag	@Api 注解用于描述整个 API 控制器或分组	@Tag 注解用于对 API 进行分组
@ApiIgnore → @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	@ApiIgnore 注解用于忽略某些 API，不在文档中显示	可以使用 @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden 注解来实现相同的效果
@ApiImplicitParam → @Parameter	@ApiImplicitParam 注解用于描述 API 方法的隐式参数	使用 @Parameter 注解
@ApiImplicitParams → @Parameters	@ApiImplicitParams 注解用于描述一组隐式参数	使用 @Parameters 注解
@ApiModel → @Schema	@ApiModel 注解用于描述数据模型	使用 @Schema 注解
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)	@ApiModelProperty(hidden = true) 注解用于隐藏模型属性	使用 @Schema(accessMode = READ_ONLY) 注解，表示属性只读且隐藏
@ApiModelProperty → @Schema	@ApiModelProperty 注解用于描述模型属性	使用 @Schema 注解
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”)	@ApiOperation 注解用于描述 API 方法的操作	使用 @Operation(summary = “foo”, description = “bar”) 注解。
@ApiParam → @Parameter	@ApiParam 注解用于描述 API 方法的参数	使用 @Parameter 注解
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)	@ApiResponse 注解用于描述 API 的响应	使用 @ApiResponse(responseCode = “404”, description = “foo”) 注解

对应的版本号差异如下：

swagger2版本：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.3.0</version>
</dependency>

swagger3版本：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>