OpenAPI 3.0 注解在 Java 数据对象中的使用规范

OpenAPI 3.0 注解在 Java 数据对象中的使用规范

在基于 OpenAPI 3.0 标准的 Java RESTful API 开发中，合理使用 OpenAPI 注解（如 SpringDoc 的 @Schema、@ParameterObject 等）对生成高质量、可读性强的 API 文档至关重要。然而，并非所有数据类都适合或需要添加这些注解。

本文档将详细说明 在哪些数据类中应添加 OpenAPI 注解，哪些不应添加或不推荐添加，并提供企业级开发的最佳实践建议。

---

一、核心原则：OpenAPI 注解的适用边界

✅ OpenAPI 注解仅应用于“直接参与 HTTP 接口契约”的数据结构
❌ 不应污染与外部接口无关的内部模型

OpenAPI 的本质是描述 API 接口的输入输出契约，因此注解应聚焦于：

• Controller 层接收的请求参数（Request Body、Query Param、Path Variable 等）
• Controller 层返回的响应体（Response Body）

---

二、各类数据对象的 OpenAPI 注解使用规范

1️⃣ ✅ 推荐添加 OpenAPI 注解的数据类

(1) DTO（Data Transfer Object）—— 请求/响应载体

适用场景：作为 Controller 方法的 @RequestBody、@ResponseBody 参数

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户创建请求")
public class UserCreateDTO {
    
    @Schema(description = "用户名", example = "zhangsan", requiredMode = Schema.RequiredMode.REQUIRED)
    private String username;
    
    @Schema(description = "邮箱", example = "zhangsan@example.com", pattern = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
    private String email;
    
    @Schema(description = "年龄", minimum = "0", maximum = "150", example = "25")
    private Integer age;
    
    // getters/setters
}

✅ 为什么推荐：

• DTO 是 API 契约的直接体现
• 字段描述、示例值、校验规则对前端/测试至关重要
• 支持 requiredMode、example、pattern 等丰富元数据

---

(2) VO（View Object）—— 响应视图对象

适用场景：Controller 返回给前端的数据结构

@Schema(description = "用户详情响应")
public class UserDetailVO {
    
    @Schema(description = "用户ID", example = "1001")
    private Long id;
    
    @Schema(description = "用户名", example = "zhangsan")
    private String username;
    
    @Schema(description = "注册时间", example = "2023-01-01T12:00:00Z")
    private LocalDateTime createTime;
    
    // 敏感字段（如密码）绝不在此暴露！
}

✅ 为什么推荐：

• VO 是 API 响应的最终形态
• 需明确告知调用方返回哪些字段、格式如何
• 可隐藏内部模型中的敏感或冗余字段

---

(3) Query Object / Search Criteria —— 查询条件封装类

适用场景：用于 @ParameterObject 或 @RequestParam 对象绑定

import io.swagger.v3.oas.annotations.ParameterObject;

@ParameterObject // SpringDoc 特有注解，表示该对象用于查询参数
@Schema(description = "用户分页查询条件")
public class UserQuery {
    
    @Schema(description = "用户名模糊搜索", example = "zhang")
    private String username;
    
    @Schema(description = "状态：0-禁用，1-启用", allowableValues = {"0", "1"}, example = "1")
    private Integer status;
    
    @Schema(description = "页码", example = "1", defaultValue = "1")
    private Integer page = 1;
    
    @Schema(description = "每页数量", example = "10", defaultValue = "10")
    private Integer size = 10;
}

✅ 为什么推荐：

• 查询参数是 API 输入的重要组成部分
• @ParameterObject 能让 Swagger UI 正确展开参数
• 避免在 Controller 方法中写几十个 @RequestParam

---

2️⃣ ❌ 不推荐或禁止添加 OpenAPI 注解的数据类

(1) Entity（实体类 / ORM 模型）

典型场景：JPA Entity、MyBatis-Plus Entity

// ❌ 错误做法：在 Entity 上加 OpenAPI 注解
@Entity
@Table(name = "user")
@Schema(description = "用户实体") // ← 不推荐！
public class User {
    @Id
    private Long id;
    
    @Column
    @Schema(description = "用户名") // ← 污染内部模型！
    private String username;
    
    @Column
    private String password; // 敏感字段！绝不应出现在 API 文档中
}

❌ 为什么不推荐：

• 职责混淆：Entity 是持久层模型，不应耦合 API 层契约
• 安全风险：Entity 通常包含敏感字段（如 password、salt），若直接暴露到 API 文档，极易造成信息泄露
• 灵活性差：API 响应结构常需与数据库结构不一致（如字段合并、格式转换），Entity 无法满足
• 维护困难：当 API 需求变更时，被迫修改数据库模型，违反分层架构原则

📌 正确做法：

• Controller 层使用 DTO/VO 与前端交互
• Service/DAO 层使用 Entity 操作数据库
• 通过 MapStruct、BeanUtils 等工具进行转换

---

(2) DO（Domain Object） / BO（Business Object）

典型场景：领域驱动设计（DDD）中的领域模型

// ❌ 不推荐
@Schema(description = "订单领域对象") // ← 领域模型不应暴露给 API
public class Order {
    private OrderId id;
    private List<OrderItem> items;
    private OrderStatus status;
    // ... 业务方法
}

❌ 为什么不推荐：

• DO/BO 是业务逻辑的核心，属于应用内部抽象
• 其结构服务于业务规则，而非 API 消费者
• 直接暴露会泄露领域实现细节，破坏封装性

---

(3) PO（Persistent Object） / 内部工具类

典型场景：MyBatis ResultMap 映射类、内部缓存对象等

// ❌ 绝对禁止
@Schema // ← 无意义且污染代码
public class UserCachePO {
    private String redisKey;
    private byte[] serializedData;
}

❌ 为什么禁止：

• 这些类完全不参与 HTTP 通信
• 添加注解纯属冗余，增加编译负担和代码噪音
• 可能误导开发者认为该类可用于 API

---

(4) 通用响应包装类（如 R、ApiResponse）

特殊情况：可选择性添加，但需谨慎

// ✅ 可接受（推荐）
@Schema(description = "统一响应格式")
public class ApiResponse<T> {
    
    @Schema(description = "状态码", example = "200")
    private Integer code;
    
    @Schema(description = "消息", example = "操作成功")
    private String message;
    
    @Schema(description = "响应数据")
    private T data; // ← 泛型，Swagger 能自动推导实际类型
}

⚠️ 注意事项：

• 仅当该包装类直接作为 Controller 返回类型时才添加
• 避免在内部服务调用的响应类上添加
• 确保 T data 字段能被 Swagger 正确识别（SpringDoc 支持泛型推导）

---

三、企业级最佳实践总结

数据类类型	是否添加 OpenAPI 注解	原因说明
DTO（请求）	✅ 强烈推荐	API 输入契约的直接载体
VO（响应）	✅ 强烈推荐	API 输出契约的直接载体
Query Object	✅ 推荐	查询参数的结构化封装
Entity	❌ 禁止	职责分离、安全、灵活性
DO / BO	❌ 禁止	领域模型不应暴露给外部
PO / 工具类	❌ 禁止	与 API 无关，纯内部使用
统一响应包装类	⚠️ 按需添加	仅当直接用于 Controller 返回

---

四、额外建议

1. 使用独立的 API 模块（可选但推荐）

project/
├── api/                ← 仅包含 DTO/VO/Exception，供前后端共享
│   ├── dto/
│   ├── vo/
│   └── ApiError.java
├── application/        ← 业务实现
└── domain/             ← 领域模型（无任何 OpenAPI 注解）

2. 避免“偷懒”直接返回 Entity

// ❌ 反模式
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) { // 直接返回 Entity
    return userService.getById(id);
}

// ✅ 正确做法
@GetMapping("/{id}")
public ApiResponse<UserDetailVO> getUser(@PathVariable Long id) {
    User user = userService.getById(id);
    UserDetailVO vo = userMapper.toVO(user);
    return ApiResponse.success(vo);
}

3. 利用 SpringDoc 的自动推导能力

• 对于简单类型（String、Long、LocalDateTime），即使不加 @Schema，Swagger 也能正确显示
• 重点为复杂对象和业务语义字段添加注解

---

五、结论

OpenAPI 注解是 API 契约的“说明书”，只应写在“对外暴露的接口数据结构”上。

遵循 “Entity 不出 Service 层，DTO/VO 不进 DAO 层” 的分层原则，不仅能提升系统安全性与可维护性，还能确保生成的 OpenAPI 文档准确、清晰、无冗余，真正成为前后端协作的桥梁，而非负担。

在代码生成器（如 MyBatis-Plus Generator）中，应仅在 DTO/VO 模板中包含 OpenAPI 注解，Entity 模板应保持纯净。