Swagger中如何使用本地图片作为@ApiImplicitParam的参数示例值

首先明确你目前写法的两个核心问题：

• @ApiImplicitParam 的 example 属性仅支持纯文本值，无法解析Markdown图片语法，你写入的图片链接不会被Swagger UI渲染
• 本地磁盘绝对路径（比如C:\\Users\\...）受浏览器安全策略限制，无法被跑在浏览器中的Swagger UI直接访问，就算语法正确也不会加载成功

根据你的实际使用场景，可选择以下任意一种方案实现：

方案1：参数本身为文件上传类型 #

如果你这个参数是用于上传图片的文件类型参数，不需要手动写示例图片，修改注解配置即可，Swagger UI会自动生成文件选择控件：

@ApiImplicitParams({
        @ApiImplicitParam(
                name = "userAvatar",
                required = true,
                paramType = "form",
                dataType = "MultipartFile",
                value = "用户头像，仅支持jpeg/png格式，文件大小不超过2M"
        )
})

方案2：字符串参数需要附图片示例 #

如果你这个参数是字符串类型，只是需要在参数说明里附上参考示例图，按以下步骤操作：

1. 把你要展示的图片放到项目静态资源目录，比如Spring Boot项目的resources/static/swagger-examples/路径下
2. 修改注解，把图片写到value属性中，用Swagger UI支持的HTML <img>标签引用：

@ApiImplicitParams({
        @ApiImplicitParam(
                name = "username",
                required = true,
                paramType = "form",
                dataType = "String",
                value = "Username Customer Owner，填写示例参考：<br> <img src='/swagger-examples/KTPHD.jpeg' width='300' />",
                example = "按上方示例图内容填写即可"
        )
})

注意：如果你的项目配置了静态资源拦截规则，需要将/swagger-examples/**路径加入放行列表，避免图片无法加载。

方案3：不想把图片存入项目的临时方案 #

如果是个人本地调试使用，不想把图片存入项目代码，可以把图片转成Base64编码，直接写入img标签的src属性中：

@ApiImplicitParam(
        name = "username",
        required = true,
        paramType = "form",
        dataType = "String",
        value = "Username Customer Owner，填写示例参考：<br> <img src='data:image/jpeg;base64,此处替换为你图片转成的Base64字符串' width='300' />"
)

该方案会让注解代码变得非常臃肿，仅推荐本地临时调试使用，不建议提交到生产代码中。

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