使用Java注解，我可以使用oneOf注解覆盖抽象字段来覆盖Swagger文档创建吗？

Question

我正在使用 Swagger UI 为我的 Spring Boot API 创建文档。结果几乎如我所愿，但“oneOf”注释引起了一个小问题。

首先，我在我的 pom.xml 文件中添加了

springdoc-openapi-starter-webmvc-ui

作为依赖项：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

我的 Swagger UI 的一些架构定义是从抽象类扩展而来的。这就是我遇到问题的地方。

该 API 旨在返回打包在分页对象中的搜索结果列表。搜索结果抽象定义如下（我省略了模式字段描述，以便于阅读）：

@Data
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;
}

我有两个课程扩展

SearchItemData

：

@EqualsAndHashCode(callSuper = true)
@Data
public class ProjectData extends SearchItemData {
    // ...
}

@EqualsAndHashCode(callSuper = true)
@Data
public class ProcurementData extends SearchItemData {
    // ...
}

从端点获取结果时，它被打包在一个

SearchItemPage

对象中：

@Data
public class SearchItemPage {
    int page;
    int pageCount;
    int pageSize;
    long totalResults;
    // TODO anyOf
    @Schema(
            description = "Array of projects and/or procurements, matching the search parameters",
            oneOf = { ProjectData.class, ProcurementData.class }
    )
    List<SearchItemData> results;
    Long procurementCount;
    Long projectCount;
}

问题是，在部署应用程序并打开生成的 Swagger UI 时，我得到以下信息：

ProjectData 和 ProcurementData 的架构是正确的，但继承似乎与“oneOf”注释不太相配。我可以看到出错的逻辑，但我很难找到解决方案。

我尝试将列表定义为

List<? extends SearchItemData>

，但这并没有真正做任何事情。

我见过有些人使用接口，这对我来说需要一些解决方法，而且我不太确定它在这里是否有效。而且我找不到覆盖自动方案定义创建的方法，因为我在库文档中缺少一些用例示例。

Answer 1

您可能需要添加类似的内容

@Schema(allOf = ParentClass.class)

在派生类中和

@Schema(subTypes = {DerivedClassA.class, DerivedClassB.class},
    discriminatorProperty = "type",
    discriminatorMapping = {
            @DiscriminatorMapping(value = "typeA", schema = DerivedClassA.class),
            @DiscriminatorMapping(value = "typeB", schema = DerivedClassB.class)
    })

在父班。