Spring Boot 3 WebFlux OpenAPI响应数组字段未正确渲染问题排查

1. 内部嵌套Record的Schema识别缺陷：Spring Doc OpenAPI 2.4在处理嵌套于ScoreResponse中的内部Score record时，自动扫描机制未能正确递归识别该内部类结构。尽管Java内部record默认是静态的，但Spring Doc的模型转换器解析List<Score>时，无法自动生成Score对应的Schema，只能 fallback 到默认string类型占位，同时因找不到Score的Schema引用，引发JSON Pointer解析错误。
2. 引用路径解析失败：由于Score是内部类，Spring Doc生成的Schema引用路径格式存在问题，导致Swagger UI无法正确解析$ref指向的Schema，进而抛出错误提示。

以下几种方案比手动注册Schema更简洁，且贴合Spring Doc原生用法：

方案1：给内部Record添加@Schema注解显式声明 #

在Score record上添加@Schema注解指定唯一Schema名称，引导Spring Doc精准识别并生成正确结构：

public record ScoreResponse(
  Integer avgScore,
  List<Score> score
){
  @Schema(name = "Score")
  public record Score(
    Integer scoreId,
    Integer score
  ){}
}

无需额外编写Bean，通过注解即可让Spring Doc自动生成数组元素对应的Schema。

方案2：将内部Record提取为顶级类 #

若业务逻辑允许，把Score从ScoreResponse中提取为独立顶级record类，从根源避免嵌套类的扫描识别问题：

// 顶级类
public record Score(
  Integer scoreId,
  Integer score
){}

public record ScoreResponse(
  Integer avgScore,
  List<Score> score
){}

该方案不仅解决Schema识别问题，还能让代码结构更清晰。

方案3：配置Spring Doc的扫描包范围 #

确保Spring Doc能扫描到所有需要生成Schema的类（包括内部类），在配置文件中添加扫描包配置：

springdoc:
  packages-to-scan: com.your.package  # 替换为你的实体类所在包路径

此配置会让Spring Doc主动扫描指定包下的所有类，自动生成对应的Schema。

方案4：优化自定义Schema注册Bean（特殊场景用） #

若需保留自定义注册方式，可简化代码，无需手动调用ModelConverters：

@Bean
public OpenApiCustomizer schemaCustomizer() {
    return openApi -> openApi
        .schema("Score", new Schema<Score>()
            .addProperty("scoreId", new IntegerSchema())
            .addProperty("score", new IntegerSchema()));
}

这种硬编码方式灵活性较低，仅推荐在特殊场景下使用。

应用上述任意方案后，Swagger UI会正确渲染score数组结构，示例响应将显示预期的对象数组，同时解析错误会消失。

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