@Schema

@Schema 是 Swagger/OpenAPI 规范中用于描述数据模型（如 Java 类、字段等）的注解，主要用在 Springdoc OpenAPI（替代 Swagger UI 的新一代工具）或 Swagger Core 中。它的作用是给 API 文档添加元数据，比如字段的描述、示例值、是否必填等，让生成的接口文档更清晰易懂。

基本作用

@Schema 可以标注在类、字段/属性、方法参数或返回值上，用来定义：

• 字段的名称、描述、数据类型
• 是否必填（required）
• 示例值（example）
• 枚举值（allowableValues）
• 格式（如日期格式 date-time）
• 隐藏字段（不显示在文档中）

pom 依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

访问文档：http://localhost:8080/swagger-ui.html（或 http://localhost:8080/swagger-ui/index.html）

1. 标注 DTO 字段说明

public class UserRegisterReq {

    @Schema(description = "手机号", example = "13800138000", requiredMode = Schema.RequiredMode.REQUIRED)
    private String phone;

    @Schema(description = "用户密码", example = "123456")
    private String password;

    @Schema(description = "昵称", example = "张三")
    private String nickname;
}

2. 标注 Controller 参数

@PostMapping("/user/register")
public void register(
        @RequestBody 
        @Schema(description = "注册请求参数")
        UserRegisterReq req
) {
}

3. 标注返回对象

@Schema(description = "用户信息返回对象")
public class UserDTO {

    @Schema(description = "用户ID", example = "1001")
    private Long id;

    @Schema(description = "用户名", example = "tom")
    private String username;
}

4. 枚举示例

@Schema(description = "设备状态", allowableValues = {"ONLINE", "OFFLINE", "FAULT"})
private String status;

5. Controller 类

@Tag(name = "用户管理")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(summary = "用户注册", description = "用于新用户注册账号")
    @PostMapping("/register")
    public void register(@RequestBody UserRegisterReq req) {
    }
}