Spring Boot 3 OpenAPI：数组字段未渲染，如何解决？

Spring Boot 3 OpenAPI 响应中数组字段未渲染：原因与解决方案

作为一名经验丰富的开发者和技术博主，我今天将深入探讨一个常见问题：在 Spring Boot 3 中，使用 Spring Doc OpenAPI 2.4 和 Webflux 时，响应实体中包含的数组字段未能在 OpenAPI UI 中正确渲染。

问题

在使用上述技术栈开发应用程序时，我遇到了一个恼人的问题。当我尝试在 OpenAPI UI 中查看响应时，我发现响应实体中包含的数组字段没有被正确地呈现出来。更确切地说，数组字段中的值显示为字符串，而不是预期的嵌套对象。此外，OpenAPI UI 显示了一条错误消息，指出它无法解析数组字段的引用。

原因分析

经过一番深入调查，我发现问题根源在于 OpenAPI 无法自动检测到数组字段中元素的类型。OpenAPI 根据字段的声明类型（在本例中为 List<Score>）进行渲染，但这还不够。它需要更多信息来确定元素的实际类型（Score）。

解决方法

解决此问题的办法有两种：

方法 1：使用 OpenAPICustomizer

使用 OpenAPICustomizer 可以向 OpenAPI 文档中添加 Score 类的模式定义。以下代码演示了如何实现：

@Bean
public OpenApiCustomizer schemaCustomizer() {
    ResolvedSchema resolvedSchema = ModelConverters.getInstance()
        .resolveAsResolvedSchema(new AnnotatedType(Score.class));
    return openApi -> openApi
        .schema(resolvedSchema.schema.getName(), resolvedSchema.schema);
}

方法 2：使用 @Schema 注解

另一种方法是使用 @Schema 注解来指定 Score 类的具体实现。在 Score 类中添加以下注解即可：

@Schema(implementation = Score.class)
public record Score(
    Integer scoreId,
    Integer score
){

  // getters and setters...
}

总结

以上两种方法都可以有效解决 Spring Boot 3 OpenAPI 中响应数组字段未渲染的问题。根据具体情况，你可以选择最合适的方法。

常见问题解答

1. 为什么会出现这个错误？

OpenAPI 无法自动检测到数组字段中元素的类型，需要额外的信息来确定。

2. 如何使用 OpenAPICustomizer 解决问题？

通过添加 OpenAPICustomizer bean 定义，你可以向 OpenAPI 文档中添加 Score 类的模式定义。

3. 如何使用 @Schema 注解解决问题？

在 Score 类中添加 @Schema 注解，指定其具体实现。

4. 除了上面提到的方法，还有其他解决办法吗？

目前已知的方法只有上述两种。

5. 如何避免此错误再次出现？

使用 OpenAPICustomizer 或 @Schema 注解来显式定义数组字段中元素的类型。