springdoc-openapi 1.5.7 如何配置响应展示为["A","B","C"]字符串数组

原有配置无效的核心原因 #

之前写的代码最终生成["string"]的默认占位，本质是两个写法的问题：

• 拆分多个独立@ExampleObject条目时，SpringDoc 1.5.7会把每个条目识别为可切换的独立响应示例，而非同一个示例内的数组元素。拆分后三个示例分别对应单值"A"、"B"、"C"，和预期的数组结构完全不匹配
• 没有在示例中完整定义数组的实际内容，框架会自动按照String数组的schema规则生成默认占位值，也就是所有元素都是"string"的空占位结构

正确配置代码 #

@Operation(summary = "字符串数组返回接口")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "OK",
                content = {@Content(mediaType = "application/json",
                        // 保留原有数组结构定义，明确响应为String类型数组
                        array = @ArraySchema(schema = @Schema(implementation = String.class)),
                        examples = {@ExampleObject(
                                name = "默认返回示例",
                                value = "[\"A\", \"B\", \"C\"]"
                        )}
                )})

配置注意事项 #

• 数组结构的schema定义不需要调整，原有写法已经可以正确告知文档生成器当前响应是元素类型为字符串的数组
• 示例值不要拆成多个@ExampleObject，只需要在单个示例对象的value属性中，传入完整转义后的目标JSON字符串即可
• 配置完成后，Swagger UI的响应预览区域会直接渲染["A","B","C"]的目标效果，不会再出现默认的"string"占位
• 如果需要在Schema文档的可选项中展示可用值，可以在数组元素的@Schema注解上增加allowableValues = {"A", "B", "C"}属性，不会干扰示例的展示效果

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