SpringBoot中Swagger UI配置RequestBody示例不显示问题

问题根因 #

你引入的springfox-boot-starter 3.0.0版本对 OpenAPI 3（Swagger v3）标准注解的支持存在未修复的兼容缺陷，无法正确解析@Content注解下通过@ExampleObject配置的自定义请求体示例，无论将注解放置在参数层还是方法层都不会生效。

可行解决方案 #

方案1：替换为Spring官方生态维护的springdoc-openapi依赖（推荐） #

Springfox 项目已停止维护多年，上述注解兼容问题官方始终没有推出修复版本，替换为springdoc-openapi可以原生支持OpenAPI 3标准注解，无需修改原有业务注解代码：

• 第一步：移除pom.xml中原有的springfox依赖

<!-- 删除原有springfox依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

• 第二步：引入对应版本的springdoc依赖：SpringBoot 2.x版本使用1.x版本依赖，SpringBoot 3.x版本使用2.x版本依赖

<!-- SpringBoot 2.x 适用 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

替换完成后重启项目，原有代码中配置的@ExampleObject(value = "foobar")就会正常展示在Swagger UI的请求体示例区域。如果需要配置JSON格式的实体类示例，直接将value属性赋值为标准JSON字符串即可，示例如下：

@io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "待创建的人员信息，JSON格式",
        content = @Content(
                examples = @ExampleObject(value = "{\"firstName\":\"张\",\"lastName\":\"三\"}")
        )
)

方案2：保留springfox 3.0.0依赖的兼容写法 #

如果暂时无法替换依赖，可以使用springfox原生支持的@ApiModelProperty注解为实体字段配置示例值，该方式在3.0.0版本中可以正常解析：
修改PersonDTO类，添加对应注解配置：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "人员信息实体")
class PersonDTO{
    @ApiModelProperty(value = "名", example = "三")
    String firstName;
    @ApiModelProperty(value = "姓", example = "张")
    String lastName;

    public PersonDTO() {}
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}

配置完成后，Swagger UI会自动拼接各字段的示例值，生成完整的JSON请求体示例，无需在@RequestBody注解中额外配置@ExampleObject。

注意：springfox 3.0.0不支持配置非实体结构的纯字符串请求体示例（比如你预期展示的"foobar"），如果有这类需求只能选择方案1替换依赖。

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