详解JAVA中的@Schema注解

时间：2025-03-18 20:18:01

目录

  • 前言
  • 1. 基本知识
  • 2. 差异

前言

由于更换新项目，最初看到@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：指定该属性的必需性
    表示这个属性是必需
  • 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版本：

<!-- /artifact//springfox-swagger2 -->
<dependency>
    <groupId></groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.3.0</version>
</dependency>

swagger3版本：

<!-- /artifact//springfox-boot-starter -->
<dependency>
    <groupId></groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

相关文章