Spring Boot中OpenAPI文档泛型与嵌套数组注解配置问询

针对你用 springdoc-openapi-starter-webmvc-ui:2.1.0 生成 OAS3 文档时遇到的泛型包装类、字典、二维数组的文档描述问题，以下是务实的实现方案：

一、处理泛型包装类 DetailedResponse<T> #

无需为每个泛型参数定义单独的非泛型子类，可通过注解指定泛型实际类型：

1. 接口方法级精准指定 #

在控制器方法上，通过 @ApiResponse 明确泛型 T 的具体类型：

@GetMapping("/user/{id}")
@ApiResponse(
    responseCode = "200",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(
            implementation = DetailedResponse.class,
            subTypes = {User.class} // 指定泛型T的实际类型
        )
    )
)
public DetailedResponse<User> getUser(@PathVariable String id) {
    // 业务逻辑
}

2. 全局配合接口补充 #

先给泛型类添加基础注解：

@Schema(type = "object")
public class DetailedResponse<T> {
    @Schema(description = "响应状态码")
    private Integer code;
    @Schema(description = "响应提示信息")
    private String message;
    @Schema(description = "响应数据") // 留空由接口指定具体类型
    private T data;
    // getter/setter
}

再在接口中细化 data 字段的类型：

@GetMapping("/orders")
@ApiResponse(
    responseCode = "200",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(
            implementation = DetailedResponse.class,
            properties = {
                @SchemaProperty(
                    name = "data",
                    schema = @Schema(implementation = List.class, subTypes = {Order.class})
                )
            }
        )
    )
)
public DetailedResponse<List<Order>> getOrderList() {
    // 业务逻辑
}

二、处理字典类型 Map<T,R> #

利用 OAS3 原生的字典支持，通过 @Schema 描述键值类型：

1. 直接在方法上定义 #

@GetMapping("/user-map")
@ApiResponse(
    responseCode = "200",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(
            type = "object",
            additionalProperties = @Schema(implementation = User.class) // 指定值的类型
            // 若键为非String类型，补充指定键类型：type = "integer"
        )
    )
)
public Map<String, User> getUserMap() {
    // 业务逻辑
}

2. 通用字典DTO（可选） #

如果某类字典频繁使用，可封装通用类减少重复注解：

@Schema(type = "object")
public class GenericDict<K, V> {
    // 无需显式定义map字段，直接通过注解描述字典结构
}

接口中使用时只需指定键值类型即可，写法和上面一致。

三、处理二维数组 T[][] #

通过嵌套的 @Schema 描述数组层级：

@GetMapping("/string-2d")
@ApiResponse(
    responseCode = "200",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(
            type = "array",
            items = @Schema(
                type = "array",
                items = @Schema(implementation = String.class) // 指定最内层元素类型
            )
        )
    )
)
public String[][] getString2DArray() {
    // 业务逻辑
}

如果是自定义对象的二维数组，将 implementation 替换为对应的DTO类即可。

额外优化配置 #

在 application.yml 中开启泛型属性自动解析，减少手动注解工作量：

springdoc:
  api-docs:
    resolve-schema-properties: true

内容的提问来源于stack exchange，提问作者G. B. Wanscher