如何在springdoc-openapi的@Schema中添加多示例并维护在模型类？

安全阿岳

2026-8-19

在Springdoc-OpenAPI的模型类中为@Schema添加多示例的实现方案

完全可行，已有大量开发者实现了这个需求，核心是通过叠加@ExampleObject注解来实现，无需在接口层重复定义示例，让代码更整洁且示例与模型同步。

实现方式1：为模型字段添加多示例

直接在模型类的字段上叠加多个@ExampleObject注解，Springdoc-OpenAPI会自动识别并在Swagger UI中展示多个可选示例：

public class User {
    @Schema(description = "用户唯一标识")
    @ExampleObject(name = "数字型ID", value = "1001")
    @ExampleObject(name = "字符串型ID", value = "usr_202405")
    private String userId;

    @Schema(description = "用户年龄")
    @ExampleObject(value = "22")
    @ExampleObject(value = "35")
    private Integer age;
}

在Swagger UI中，对应字段的示例区域会出现切换选项，方便查看不同场景的示例值。

实现方式2：为整个模型类添加多示例

如果需要给整个模型对象设置多组完整示例，可在类级别叠加@ExampleObject：

@Schema(description = "用户信息模型")
@ExampleObject(name = "在校用户", value = "{\"userId\":\"1001\", \"age\":22, \"username\":\"小明\"}")
@ExampleObject(name = "职场用户", value = "{\"userId\":\"usr_202405\", \"age\":35, \"username\":\"张工\"}")
public class User {
    private String userId;
    private Integer age;
    private String username;
}

这种方式会在模型的示例展示区，提供多个完整的对象结构示例，更直观展示不同场景下的模型数据。