springdoc-openapi 1.6.8：如何在响应中正确展示对象列表示例？

针对你遇到的raoGroup数组在Swagger-UI里只显示["string"]而非对象结构的问题，试试下面几个配置方案：

方案1：在DTO字段上明确指定数组元素类型 #

在UserPrincipalDTO的raoGroup字段上，同时用@Schema和@ArraySchema注解明确指定数组项的类型，不要只依赖@ArraySchema：

@Schema(description = "RaoGroup分组列表", implementation = RaoGroupDTO.class)
@ArraySchema(schema = @Schema(implementation = RaoGroupDTO.class))
private List<RaoGroupDTO> raoGroup;

springdoc 1.6.8版本中，@ArraySchema需要显式关联内部对象的schema，否则会默认解析成字符串数组。

方案2：全局配置时关联正确的对象Schema #

如果是在OpenApiConfig里自定义响应结构，要确保数组Schema的items属性指向RaoGroupDTO的Schema，而不是只设置类型为array：

@Bean
public OpenAPI customOpenAPI() {
    // 定义RaoGroupDTO的Schema
    Schema<RaoGroupDTO> raoGroupSchema = new Schema<>();
    raoGroupSchema.addProperty("name", new Schema<>().type("string").example("测试分组1"));
    
    // 定义数组Schema，关联上面的对象Schema
    Schema<List<RaoGroupDTO>> raoGroupArraySchema = new Schema<>();
    raoGroupArraySchema.type("array").items(raoGroupSchema);
    
    // 组装响应的Schema
    Schema<UserPrincipalDTO> userSchema = new Schema<>();
    userSchema.addProperty("raoGroup", raoGroupArraySchema);
    
    return new OpenAPI()
            .components(new Components()
                    .schemas(Map.of("UserPrincipalDTO", userSchema))
            )
            .paths(new Paths()
                    .addPathItem("/your-api", new PathItem()
                            .get(new Operation()
                                    .responses(new ApiResponses()
                                            .addApiResponse("200", new ApiResponse()
                                                    .description("请求成功")
                                                    .content(new Content()
                                                            .addMediaType(MediaType.APPLICATION_JSON_VALUE, 
                                                                    new MediaType().schema(new Schema<>().$ref("#/components/schemas/UserPrincipalDTO"))
                                                            )
                                                    )
                                            )
                                    )
                    )
            );
}

方案3：确保RaoGroupDTO被正确扫描 #

检查RaoGroupDTO类是否添加了@Schema注解，且字段有正确的配置，同时该类在Spring的扫描路径下：

@Schema(description = "分组信息DTO")
public class RaoGroupDTO {
    @Schema(description = "分组名称", example = "默认分组")
    private String name;
    
    // 其他字段、getter和setter方法
}

只有springdoc能扫描到DTO的注解信息，才能生成对应的对象结构示例。

内容的提问来源于stack exchange，提问作者Mr.Kao