Springdoc OpenAPI 中 @Schema oneOf 配置失效问题解析

问题背景

在 Spring Boot 应用中使用 Springdoc OpenAPI 生成 API 文档时，开发者可能会遇到 @Schema 注解的 oneOf 配置被忽略的情况。具体表现为：当在 POJO 字段上使用 @Schema(oneOf = {Child1.class, Child2.class}) 注解时，生成的 OpenAPI 文档中仍然包含了所有子类，而不仅仅是注解中指定的子类。

问题复现

假设我们有以下类结构：

// 父类定义
@JsonSubTypes({
    @JsonSubTypes.Type(value = Child1.class),
    @JsonSubTypes.Type(value = Child2.class),
    @JsonSubTypes.Type(value = Child3.class),
})
public abstract class Parent {
    private String parentProperty;
}

// 子类定义
public class Child1 extends Parent {
    private String childProperty1;
}

public class Child2 extends Parent {
    private String childProperty2;
}

public class Child3 extends Parent {
    private String childProperty3;
}

// 请求体定义
public class MyRequest {
    @Schema(oneOf = {Child1.class, Child2.class})
    private Parent parent;
}

理想情况下，生成的 OpenAPI 文档应该只包含 Child1 和 Child2 作为 parent 字段的可能类型。然而实际生成的文档中却包含了所有三个子类。

技术分析

这个问题的根源在于 Springdoc OpenAPI 在处理 @Schema 注解的 oneOf 属性时，与 Jackson 的 @JsonSubTypes 注解产生了冲突。具体表现为：

1. 注解优先级问题：Springdoc 在处理类型定义时，可能会优先考虑 @JsonSubTypes 中定义的所有子类，而忽略了 @Schema 中的 oneOf 限制。

2. 类型解析流程：在类型解析过程中，Springdoc 的类型解析器可能没有正确处理 @Schema 注解中的 oneOf 属性，导致它被后续的处理步骤覆盖。

3. 文档生成机制：OpenAPI 文档生成时，对于多态类型的处理可能没有充分考虑开发者通过 @Schema 注解提供的显式类型约束。

解决方案

虽然当前版本(2.6.0)存在这个问题，但开发者可以考虑以下解决方案：

1. 自定义类型解析器：实现自定义的 ModelConverter 来覆盖默认的类型解析行为，确保 @Schema 的 oneOf 配置被正确应用。

2. 使用 OpenAPI 注解替代：考虑使用 @Schema 的其他属性或 OpenAPI 的其他注解来达到相同的文档效果。

3. 等待官方修复：关注 Springdoc OpenAPI 的更新，这个问题可能会在未来的版本中得到修复。

最佳实践

在使用多态类型和 OpenAPI 文档生成时，建议：

1. 保持一致性：确保 @JsonSubTypes 和 @Schema 注解中的类型定义一致，避免冲突。

2. 明确文档意图：如果某些子类不应该出现在 API 文档中，考虑重构类层次结构，而不是依赖文档注解来过滤。

3. 测试文档输出：在重要的 API 变更后，验证生成的 OpenAPI 文档是否符合预期。

总结

Springdoc OpenAPI 是一个强大的工具，但在处理复杂的类型系统和文档注解时可能会遇到一些边界情况。理解这些限制并掌握相应的解决方案，可以帮助开发者生成更准确、更有用的 API 文档。对于这个特定的 oneOf 配置问题，开发者需要权衡短期解决方案和长期维护成本，选择最适合项目需求的方案。