Spring Boot中oneOf注解结合抽象类继承生成Swagger文档异常求助

问题根源 #

你之前直接在List<SearchItemData>字段上标注@Schema(oneOf=...)，但这个配置会被springdoc解析为整个列表对象的多态，而非列表中每个元素的多态，这直接导致了Swagger UI显示异常。另外，抽象类的继承关系未明确告知OpenAPI，也会干扰多态Schema的正常生成。

修复步骤 #

1. 给抽象类添加继承元数据

在SearchItemData抽象类上添加@Schema注解，明确声明它的子类，让OpenAPI识别多态关系：

@Data
@Schema(subTypes = {ProjectData.class, ProcurementData.class})
public abstract class SearchItemData {
    private String externalId;
    private String type;
    private String name;
    private String description;
    @JsonFormat(shape = JsonFormat.Shape.STRING, timezone = "Europe/Copenhagen")
    private Date published;
    private String address;
    private String phase;
    private Long estimatedSum;
    private Long buildingArea;
    private String projectStart;
    private String projectEnd;
    private List<RoleData> roles;
}

2. 修正列表字段的@Schema配置

将oneOf配置转移到列表的items属性中，明确指定数组元素的多态类型：

@Data
public class SearchItemPage {
    int page;
    int pageCount;
    int pageSize;
    long totalResults;

    @Schema(
        description = "Array of projects and/or procurements, matching the search parameters",
        type = "array",
        items = @Schema(oneOf = {ProjectData.class, ProcurementData.class})
    )
    List<SearchItemData> results;

    Long procurementCount;
    Long projectCount;
}

可选优化：给子类显式命名（避免Schema名称冲突）

如果需要更清晰的Schema命名，可以给每个子类添加@Schema注解：

@EqualsAndHashCode(callSuper = true)
@Data
@Schema(name = "ProjectData")
public class ProjectData extends SearchItemData {
    // ... 子类字段
}

@EqualsAndHashCode(callSuper = true)
@Data
@Schema(name = "ProcurementData")
public class ProcurementData extends SearchItemData {
    // ... 子类字段
}

验证效果 #

重启应用后打开Swagger UI，查看SearchItemPage的results字段：数组中的每个元素会显示为可选择ProjectData或ProcurementData的结构，继承的字段也会正确展示。

内容的提问来源于stack exchange，提问作者JaisBC