SpringBoot+springdoc-openapi-ui：数组URL参数示例不显示问题

我之前也碰到过类似的坑，咱们先来拆解你遇到的两个问题的根源，再给出具体的解决办法：

问题根源分析 #

1. 示例值格式错误
   你在@Parameter里写的example = "[f1,f2,f3]"是一个带方括号的字符串，而springdoc对于数组类型的参数，需要的是数组形式的示例值，不是字符串。swagger会把这个字符串当成单个参数值，自然不会在输入框里显示成数组的样子，请求时也会把整个字符串作为一个数组元素发送，导致后端收到的参数不符合预期。

2. Schema配置不匹配
   你手动指定content = @Content(array = @ArraySchema(schema = @Schema(type = "string")))的写法有点冗余，springdoc对于@RequestParam的数组参数，其实可以更简洁地配置，这种绕弯的配置反而可能导致swagger识别错误。

具体解决办法 #

方法一：修正@Parameter的示例和Schema配置 #

把示例改成JSON数组格式，同时调整Schema的写法，让swagger正确识别数组类型：

@Parameters(value = { 
    @Parameter(in = ParameterIn.QUERY, 
               name = "output", 
               examples = @ExampleObject(value = "[\"f1\",\"f2\",\"f3\"]"),
               content = @Content(schema = @Schema(type = "array", items = @Schema(type = "string")))) 
})
public ResponseEntity<Object> showReportData(@RequestParam(value = "output") String[] outputFields) {
    // 业务逻辑代码
}

这里用examples配合@ExampleObject传入JSON格式的数组字符串，swagger就能正确解析并在输入框里显示示例值了。

方法二：更简洁的@Schema注解（推荐） #

直接在参数上用@Schema注解，不需要额外的@Parameters和@Parameter，springdoc会自动识别参数类型并生成正确的swagger文档：

public ResponseEntity<Object> showReportData(
    @RequestParam(value = "output") 
    @Schema(example = {"f1", "f2", "f3"}, 
            type = "array", 
            items = @Schema(type = "string")) 
    String[] outputFields) {
    // 业务逻辑代码
}

这种写法更直观，也不容易出错，示例值直接用Java数组形式，swagger会自动处理成正确的展示格式。

方法三：配置数组参数的请求风格（可选） #

如果希望swagger UI用逗号分隔的形式发送数组参数（比如output=f1,f2,f3），而不是默认的多参数形式（output=f1&output=f2&output=f3），可以在application.properties里添加配置：

springdoc.swagger-ui.query-config.array-style=comma

这样请求时参数格式就会符合你的预期了。

验证效果 #

修改完代码后重启服务，打开swagger UI就能看到output参数的输入框里显示出f1,f2,f3的示例值，点击执行后，请求参数会以正确的数组形式发送（多参数或逗号分隔，取决于你的配置），后端也能正确接收到String[]类型的参数。

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