SpringDoc OpenAPI 泛型返回值完美解决方案

🔍 问题原因分析

根本原因 ：SpringDoc OpenAPI 在处理泛型返回类型时，@Schema 注解标注在泛型类 R<T> 上，但没有使用 implementation 属性指定泛型的具体类型。SpringDoc 无法在运行时自动推断泛型参数 T 的实际类型，因此所有接口都显示相同的 data 结构（通常是 Object 或第一次解析到的类型）。

关键问题点：

1. R<T> 类的 data 字段没有指定 implementation
2. SpringDoc 默认会将泛型 T 解析为 Object 或缓存的第一个类型

---

✅ 解决方案

需要在 Controller 方法上使用 @Operation 的 responses 属性，或者使用 @ApiResponse + @Content + @Schema(implementation = ...) 显式指定返回类型。

但更优雅的方式是：直接在 Controller 方法上使用 @Schema 注解指定返回类型的实现类。

方案一：修改 Controller（推荐）

在每个接口方法上添加 @ApiResponse 注解显式指定返回类型：

@Operation(summary = "查询所有医学系统")
@ApiResponse(responseCode = "200", description = "成功",
    content = @Content(schema = @Schema(implementation = R_MedicalSystemVO_List.class)))
@GetMapping("/systems")
public R<List<MedicalSystemVO>> listAllSystems() { ... }

但这种方式需要为每个泛型组合创建单独的 Schema 类，比较繁琐。

---

方案二：使用 @Schema 的 oneOf 属性（不推荐）

这种方式会导致文档结构复杂化。

---

方案三：最佳实践 - 为常用泛型组合创建专用 Schema 类

📋 问题原因分析

根本原因

SpringDoc OpenAPI 在处理泛型返回类型 R<T> 时存在以下问题：

1. 类型擦除 ：Java 泛型在运行时会被擦除，SpringDoc 无法通过反射获取 T 的实际类型
2. Schema 缓存 ：当 @Schema(name = "R") 固定时，SpringDoc 会缓存第一次解析的 Schema，导致后续所有接口都显示相同的结构
3. 缺少 implementation 属性 ：data 字段的 @Schema 没有指定 implementation，SpringDoc 默认解析为 Object

---

✅ 解决方案总结

1. Result/R 类正确写法

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "统一接口应答封装")  // 不要固定 name
public class R<T> implements Serializable {

    @Schema(description = "业务状态码", example = "0")
    private int code;

    @Schema(description = "提示信息", example = "OK")
    private String msg;

    @Schema(description = "业务数据")
    private T data;

    @Schema(description = "响应时间")
    private LocalDateTime timestamp;

    // ... 静态方法
}

关键点 ：移除 @Schema(name = "R") 中的固定 name，避免缓存问题。

---

2. VO 类正确写法

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(name = "MedicalSystemVO", description = "医学系统视图对象")
public class MedicalSystemVO implements Serializable {

    @Schema(description = "系统ID", example = "1")
    private Integer id;

    @Schema(description = "系统名称", example = "神经系统")
    private String systemName;

    @Schema(description = "描述", example = "主要作用...")
    private String description;
}

关键点 ：每个 VO 类都需要 @Schema(name = "xxx") 指定唯一名称。

---

3. Controller 正确写法（核心）

@Operation(summary = "查询医学系统")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功",
        content = @Content(mediaType = "application/json",
            schema = @Schema(implementation = MedicalSystemListResponse.class)))
})
@GetMapping("/systems")
public R<List<MedicalSystemVO>> listAllSystems() {
    return R.ok(systems);
}

// 为每个泛型组合创建响应 Schema 类
@Schema(name = "MedicalSystemListResponse", description = "医学系统列表响应")
public static class MedicalSystemListResponse extends R<List<MedicalSystemVO>> {}

关键点：

• 使用 @ApiResponses + @Content + @Schema(implementation = ...) 显式指定返回类型
• 创建继承 R<T> 的静态内部类，SpringDoc 会正确解析泛型参数

---

4. 效果

接口	Example Value
/api/medical/systems	{"code":0,"msg":"OK","data":[{"id":1,"systemName":"神经系统"...}]}
/api/medical/systems/{id}/terms	{"code":0,"msg":"OK","data":[{"id":1,"termCn":"哮喘"...}]}
/api/medical/terms/{id}	{"code":0,"msg":"OK","data":{"id":1,"termCn":"哮喘","oilList":[...]}}

每个接口的 data 字段会根据 VO 类型自动生成正确的 Example Value！

---

📝 最佳实践建议

1. 推荐：将响应 Schema 类放在 Controller 内部作为静态内部类（如代码所示），保持代码简洁
2. 或者 ：如果项目有多个 Controller 共用相同响应类型，可将 Schema 类提取到单独的 response 包中
3. 命名规范 ：响应 Schema 类建议命名为 XxxResponse 或 XxxListResponse，便于区分