如何在Swagger的@ApiResponse注解中添加自定义响应示例

你当前使用的是Springfox Swagger2的注解体系，原生@ApiResponse没有直接暴露示例配置属性，需要搭配同包下的@Example、@ExampleProperty注解完成自定义响应示例绑定，具体操作如下：

核心代码修改 #

直接调整接口方法上的@ApiResponses配置，为每个状态码单独绑定对应响应示例即可：

@Api(value = "test API")
@RequestMapping("/api/v1/product")
public interface TestController {

    @ApiOperation(
            value = "Service that return a Product",
            notes = "This service returns a Product by the ID",
            nickname = "getProductById",
            response = ProductResponse.class)
    @ApiResponses(value = {
            @ApiResponse(
                    code = 200,
                    message = "The request has succeeded.",
                    response = ProductResponse.class,
                    examples = @io.swagger.annotations.Example(
                            @ExampleProperty(
                                    mediaType = "application/json",
                                    value = "{\n" +
                                            "  \"product\": {\n" +
                                            "    \"id\": \"12345\",\n" +
                                            "    \"productName\": \"Product name\",\n" +
                                            "    \"productDescription\": \"This is a description\",\n" +
                                            "    \"unitPrice\": 3.25\n" +
                                            "  },\n" +
                                            "  \"customException\": null\n" +
                                            "}"
                            )
                    )
            ),
            @ApiResponse(
                    code = 500,
                    message = "Internal server error.",
                    response = ProductResponse.class,
                    examples = @io.swagger.annotations.Example(
                            @ExampleProperty(
                                    mediaType = "application/json",
                                    value = "{\n" +
                                            "  \"product\": null,\n" +
                                            "  \"customException\": {\n" +
                                            "    \"message\": \"/ by zero\",\n" +
                                            "    \"errorCode\": \"500\",\n" +
                                            "    \"errorType\": \"Internal server error\",\n" +
                                            "    \"exceptionDetail\": null,\n" +
                                            "    \"cause\": null,\n" +
                                            "    \"stackTrace\": [\n" +
                                            "      {\n" +
                                            "        \"classLoaderName\": \"app\",\n" +
                                            "        \"moduleName\": null,\n" +
                                            "        \"moduleVersion\": null,\n" +
                                            "        \"methodName\": \"getProductById\",\n" +
                                            "        \"fileName\": \"TestControllerImpl.java\",\n" +
                                            "        \"lineNumber\": 33,\n" +
                                            "        \"className\": \"com.myproject.testmicroservice.controller.impl.TestControllerImpl\",\n" +
                                            "        \"nativeMethod\": false\n" +
                                            "      }\n" +
                                            "    ]\n" +
                                            "  }\n" +
                                            "}"
                            )
                    )
            )
    })
    @GetMapping(
            value = "/productById",
            produces = { "application/json" }
    )
    ResponseEntity<ProductResponse> getProductById(@RequestParam(value = "productId", required = true) String productId);
}

配置不生效常见排查点 #

配置后如果Swagger UI没有正常展示示例，按以下顺序排查问题：

• 导包错误：@Example、@ExampleProperty必须从io.swagger.annotations包导入，不要引入Springdoc或其他三方包下的同名注解
• 版本冲突：项目中springfox-swagger2和springfox-swagger-ui的版本必须完全一致，不要混用2.9.x、3.0.0等跨大版本的Swagger依赖
• 匹配规则错误：@ExampleProperty中配置的mediaType值，必须和接口@GetMapping注解中produces声明的值完全一致，否则Swagger无法将示例和对应响应做绑定
• 缓存问题：清理浏览器缓存、重启服务，访问Swagger UI时强制刷新页面，避免加载旧的接口元数据缓存

提示：你提供的500响应示例中"product": "null,"存在JSON格式错误，null作为值不需要加引号，后面也不能带多余逗号，上述代码已经修正了这个问题，避免Swagger解析示例失败。

如果后续升级到Springdoc OpenAPI（Swagger3），注解体系会有变化，需要用@Content搭配@ExampleObject配置示例，但当前你使用的Springfox注解体系下，上述配置可以直接生效。

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