SpringDoc OpenAPI 泛型返回值完美解決方案(最新推薦)

更新時間：2026年03月31日 09:38:17 作者：凸頭

SpringDoc處理泛型返回類型時存在緩存和類型擦除問題,導致所有接口顯示相同的data結構,本文給大家介紹SpringDoc OpenAPI 泛型返回值完美解決方案,感興趣的朋友跟隨小編一起看看吧

?? 問題原因分析

根本原因：SpringDoc OpenAPI 在處理泛型返回類型時，@Schema 注解標注在泛型類 R<T> 上，但沒有使用 implementation 屬性指定泛型的具體類型。SpringDoc 無法在運行時自動推斷泛型參數 T 的實際類型，因此所有接口都顯示相同的 data 結構（通常是 Object 或第一次解析到的類型）。

關鍵問題點：

R<T> 類的 data 字段沒有指定 implementation
SpringDoc 默認會將泛型 T 解析為 Object 或緩存的第一個類型

? 解決方案

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

但更優(yōu)雅的方式是：直接在 Controller 方法上使用 @Schema 注解指定返回類型的實現類。

方案一：修改 Controller（推薦）

在每個接口方法上添加 @ApiResponse 注解顯式指定返回類型：

@Operation(summary = "查詢所有醫(yī)學系統(tǒng)")
@ApiResponse(responseCode = "200", description = "成功",
    content = @Content(schema = @Schema(implementation = R_MedicalSystemVO_List.class)))
@GetMapping("/systems")
public R<List<MedicalSystemVO>> listAllSystems() { ... }

但這種方式需要為每個泛型組合創(chuàng)建單獨的 Schema 類，比較繁瑣。

方案二：使用@Schema的oneOf屬性（不推薦）

這種方式會導致文檔結構復雜化。

方案三：最佳實踐 - 為常用泛型組合創(chuàng)建專用 Schema 類

?? 問題原因分析

根本原因

SpringDoc OpenAPI 在處理泛型返回類型 R<T> 時存在以下問題：

類型擦除：Java 泛型在運行時會被擦除，SpringDoc 無法通過反射獲取 T 的實際類型
Schema 緩存：當 @Schema(name = "R") 固定時，SpringDoc 會緩存第一次解析的 Schema，導致后續(xù)所有接口都顯示相同的結構
缺少 implementation 屬性：data 字段的 @Schema 沒有指定 implementation，SpringDoc 默認解析為 Object

? 解決方案總結

1. Result/R 類正確寫法

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "統(tǒng)一接口應答封裝")  // 不要固定 name
public class R<T> implements Serializable {
    @Schema(description = "業(yè)務狀態(tài)碼", example = "0")
    private int code;
    @Schema(description = "提示信息", example = "OK")
    private String msg;
    @Schema(description = "業(yè)務數據")
    private T data;
    @Schema(description = "響應時間")
    private LocalDateTime timestamp;
    // ... 靜態(tài)方法
}

關鍵點：移除 @Schema(name = "R") 中的固定 name，避免緩存問題。

2. VO 類正確寫法

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(name = "MedicalSystemVO", description = "醫(yī)學系統(tǒng)視圖對象")
public class MedicalSystemVO implements Serializable {
    @Schema(description = "系統(tǒng)ID", example = "1")
    private Integer id;
    @Schema(description = "系統(tǒng)名稱", example = "神經系統(tǒng)")
    private String systemName;
    @Schema(description = "描述", example = "主要作用...")
    private String description;
}

關鍵點：每個 VO 類都需要 @Schema(name = "xxx") 指定唯一名稱。

3. Controller 正確寫法（核心）

@Operation(summary = "查詢醫(yī)學系統(tǒng)")
@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);
}
// 為每個泛型組合創(chuàng)建響應 Schema 類
@Schema(name = "MedicalSystemListResponse", description = "醫(yī)學系統(tǒng)列表響應")
public static class MedicalSystemListResponse extends R<List<MedicalSystemVO>> {}

關鍵點：

使用 @ApiResponses + @Content + @Schema(implementation = ...) 顯式指定返回類型
創(chuàng)建繼承 R<T> 的靜態(tài)內部類，SpringDoc 會正確解析泛型參數

4. 效果

接口	Example Value
`/api/medical/systems`	`{"code":0,"msg":"OK","data":[{"id":1,"systemName":"神經系統(tǒng)"...}]}`
`/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！