SpringDoc @ApiResponses如何配置@Schema定义List<MyClass>返回对象

你使用的springdoc-openapi 1.5.x版本遵循OpenAPI 3规范，针对集合类型的返回值，不需要直接编写不合法的泛型类字面量，使用@ArraySchema注解指定集合元素类型即可，正确配置如下：

@Operation(....)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation",
                content = { @Content(mediaType = "application/json",
                        // 用array属性指定返回值是数组，schema指定数组元素类型
                        array = @ArraySchema(schema = @Schema(implementation = MyClass.class)) )
        }),
        @ApiResponse(...),
        @ApiResponse(...)
})
@GetMapping(value = "/aaa", produces = MediaType.APPLICATION_JSON_VALUE)
public List<MyClass> getAaa(...)
{
    return ...
}

Java泛型存在编译期类型擦除，List<MyClass>.class本身就是不符合Java语法的写法，无法通过编译。OpenAPI 3规范专门提供了@ArraySchema注解用于描述数组/集合类型的结构，只需要在注解中指定集合内部元素的实现类，Swagger UI就会自动识别返回值为List<MyClass>类型。

如果不想使用@ArraySchema，也可以自定义一个继承集合类的空类作为类型标识：

// 自定义类继承ArrayList，指定泛型为MyClass
public class MyClassList extends ArrayList<MyClass> {}

之后直接在@Schema中引用该类即可：

schema = @Schema(implementation = MyClassList.class)

该方案可以实现同样的效果，但会增加多余的自定义类，更推荐使用第一种方案。

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