1. 概述
Swagger 是目前主流的 REST API 文档规范，不仅能自动生成接口文档，还能提供参数的示例值，极大提升前后端协作效率。
但在实际使用中，有一个常见的“踩坑点”：当你想在接口请求体中传一个字符串数组（String[] 或 List<String>）时，Swagger 默认并不会展示清晰的示例数据。这会让调用方一脸懵：到底该怎么传？
比如在 Swagger Editor 中，默认生成的数组参数示例是这样的：
⚠️ 看起来是不是有点抽象？根本看不出数组里该填啥。
本文就来解决这个问题——如何为字符串数组类型的请求体参数添加清晰的示例值。
2. 问题场景：Swagger 中的字符串数组参数
当你的接口接收一个字符串数组作为 request body 时，例如：
["apple", "banana", "cherry"]
Swagger 默认的 schema 生成机制并不会自动填充 example 字段，导致前端或测试人员无法直观了解请求格式。
目标是让文档展示出类似下面这样清晰的示例：
✅ 这样一目了然，调用方直接照着填就行。
下面介绍两种解决方案：原生 YAML 配置 和 Spring Boot 项目中常用的 Springdoc 注解方式。
3. 使用 YAML 手动定义示例
如果你是手写 OpenAPI/Swagger YAML 文件，可以直接在 parameters 中指定 example。
parameters:
- in: body
description: ""
required: true
name: name
schema:
type: array
items:
type: string
example: ["str1", "str2", "str3"]
关键点：
type: array表示这是一个数组items.type: string定义元素类型为字符串- ✅
example字段显式提供示例值，Swagger UI 就能正确渲染
效果如上图所示，现在用户一看就知道该怎么传参了。
4. 使用 Springdoc 实现（Spring Boot 场景）
大多数 Java 项目使用的是 Spring Boot + Springdoc（即 springdoc-openapi），通过注解来自动生成文档。
4.1 数据模型中添加 @Schema 注解
在 DTO 类中，使用 @Schema 注解明确指定数组类型和示例值：
@Schema
public class Foo {
private long id;
@Schema(
name = "name",
type = "array",
example = "[\"str1\", \"str2\", \"str3\"]"
)
private List<String> name;
// getter & setter
}
⚠️ 注意：
example必须是合法的 JSON 字符串格式，所以要用转义引号type = "array"明确声明类型，避免推断错误
4.2 控制器接口标注 @Parameter
为了让 Swagger 知道这个参数来自哪个模型，还需要在 Controller 方法上使用 @Parameters 或 @Parameter 注解：
@RequestMapping(method = RequestMethod.POST, value = "/foos")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@Parameters({
@Parameter(name = "foo", description = "List of strings")
})
public Foo create(@RequestBody final Foo foo) {
// 业务逻辑
return foo;
}
✅ 这样 Springdoc 就能把 Foo 类中的 @Schema 示例正确映射到 UI 上。
5. 总结
| 方式 | 适用场景 | 是否推荐 |
|---|---|---|
| YAML 手动编写 | API 文档独立维护 | ✅ 适合标准化团队 |
| Springdoc 注解 | Spring Boot 项目 | ✅✅ 强烈推荐 |
核心要点：
- ❌ Swagger 默认不为数组生成示例，容易造成沟通成本
- ✅ 使用
example字段（YAML）或@Schema(example = "...")（Java）可解决 - ⚠️ 示例值必须是合法 JSON 格式，注意转义
- 推荐在所有涉及集合参数的接口中都显式添加示例，提升文档可用性
示例代码已托管至 GitHub：https://github.com/eugenp/tutorials/tree/master/spring-boot-modules/spring-boot-swagger-2