Page Type Information Lost When Wrapped in Generic Response Class - Page<T> Becomes PageObject

[wanghongzhou]

Describe the bug

When a Page<T> type is wrapped inside a generic response wrapper (like ApiResponse<Page<UserVO>>), SpringDoc loses the generic type information and generates an incorrect schema where Page<UserVO> becomes PageObject instead of maintaining the proper generic type. This happens even with VIA_DTO serialization mode enabled.

To Reproduce

Versions:

• Spring Boot: 3.5.9
• SpringDoc OpenAPI: 2.8.15
• Spring Data: 2025.0.0

Configuration:

spring:
  data:
    web:
      pageable:
        serialization-mode: VIA_DTO

Response wrapper:

@Data
@Schema(description = "Unified JSON Response")
public class ApiResponse<D> {
    @Schema(description = "Status code")
    private int code;
    
    @Schema(description = "Response data")
    private D data;  // When D is Page<UserVO>, type info is lost
}

Controller:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    @Operation(summary = "Get paginated users")
    public ApiResponse<Page<UserVO>> getUsers(Pageable pageable) {
        // Implementation
    }
}

@Data
@Schema(description = "User View Object")
class UserVO {
    @Schema(description = "Username")
    private String username;
    
    @Schema(description = "Email")
    private String email;
}

Actual OpenAPI Schema Generated:

{
  "ApiResponsePageUserVO": {
    "type": "object",
    "properties": {
      "code": { "type": "integer" },
      "data": {
        "$ref": "#/components/schemas/PageObject"  // ❌ Wrong! Should be Page«UserVO»
      }
    }
  },
  "PageObject": {  // ❌ Generic type lost
    "type": "object",
    "properties": {
      "content": {
        "type": "array",
        "items": {}  // ❌ Empty items - no UserVO type
      }
    }
  }
}

Expected OpenAPI Schema:

{
  "ApiResponsePageUserVO": {
    "type": "object",
    "properties": {
      "code": { "type": "integer" },
      "data": {
        "$ref": "#/components/schemas/PageUserVO"  // ✅ Correct reference
      }
    }
  },
  "PageUserVO": {  // ✅ Proper generic type preserved
    "type": "object",
    "properties": {
      "content": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/UserVO"  // ✅ Correct item type
        }
      },
      "pageable": { "$ref": "#/components/schemas/PageableObject" },
      "totalElements": { "type": "integer" },
      "totalPages": { "type": "integer" }
      // ... other VIA_DTO properties
    }
  },
  "UserVO": {
    "type": "object",
    "properties": {
      "username": { "type": "string" },
      "email": { "type": "string" }
    }
  }
}

Root Cause Analysis

In PageOpenAPIConverter.resolve():

if (replacePageWithPagedModel && PAGE_TO_REPLACE.equals(cls.getCanonicalName())) {
    if (!type.isSchemaProperty())
        type = resolvePagedModelType(javaType);  // ✅ Preserves generic type
    else
        type.name(getParentTypeName(type, cls)); // ❌ Only sets name, loses generic type
}

[ermengxing]

I think it's a bug, but it could have been solved in other ways, and I don't want to dig into it.
If anyone finds the answer, please reply to me.

My solution：
delete
@Schema(description = "Unified JSON Response")
public class ApiResponse {

@Schema(description = "Unified JSON Response")

delete
@Schema(description = "Response data")
private D data; // When D is Page, type info is lost

@Schema(description = "Response data")

Workaround not handling bugs: Removing @Schema on generics (description = "Unified JSON Response") @Schema(description = "Response data")

真感觉自己被驴踢了

other Use simple class names instead of fully qualified names (if turned on, you will see a long fully qualified class name)
springdoc:
use-fqn: false

[wanghongzhou]

My solution： delete @Schema(description = "Unified JSON Response") public class ApiResponse {

@Schema(description = "Unified JSON Response")

delete @Schema(description = "Response data") private D data; // When D is Page, type info is lost

@Schema(description = "Response data")

@ermengxing
I have removed all the @Schema annotations from the ApiResponse class, but the problem still remains.

[ermengxing]

@wanghongzhou I'm sorry, but I can't help you.

Versions:

Spring Boot: 3.5.9
SpringDoc OpenAPI: 2.8.15

@Data
public class ApiResult<T> implements Serializable {
    @Serial
    private static final long serialVersionUID = 6655433632808243361L;

    @Schema(name = "code", description = "接口请求状态，执行成功：200")
    private int code;
    @Schema(name = "message", description = "接口服务编码")
    private String message;

    @Schema(name = "timestamp", description = "当前系统时间值，格式：yyyy-MM-dd HH:mm:ss")
    private String timestamp ;

    private T data;

    public String getTimestamp() {
        return String.valueOf(System.currentTimeMillis());
    }

    public ApiResult(int code, String message, String timestamp, T data) {
        this.code = code;
        this.message = message;
        this.timestamp = timestamp;
        this.data = data;
    }

Everything is fine