Spring Boot/Springfox Swagger UI无法显示响应示例与模型求助

我来帮你捋清楚这个问题——你用Springfox生成Swagger文档时，不管用V2还是OAS3.0的注解，都没法显示响应的示例值和模型，核心原因其实出在返回类型的定义和注解混用上，咱们一步步来解决：

先分析你遇到的核心问题 #

1. 返回类型不匹配：你的控制器方法返回的是ResponseEntity<Object>，而不是ResponseEntity<Car>。即使你在注解里指定了response = Car.class或者schema = @Schema(implementation = Car.class)，Springfox会优先识别方法的实际返回类型，Object类型会让它无法正确推断出具体的模型结构。
2. 注解版本混用：在尝试OAS3.0时，你同时用了V2的@ApiModel/@ApiModelProperty和V3的@Schema注解，两套注解冲突会导致Springfox无法正确解析模型元数据。

方案1：修正Swagger V2注解的用法（如果坚持用V2规范） #

步骤1：修改控制器返回类型 #

把ResponseEntity<Object>改成ResponseEntity<Car>，让Springfox能直接识别返回的模型类型：

@GetMapping(path = "/car")
@ApiOperation(value = "Get car by color.", response = Car.class)
@ApiParam(value = "Color of the car.", required = true)
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "OK.", response = Car.class),
    @ApiResponse(code = 400, message = "Invalid color provided."),
    @ApiResponse(code = 404, message = "Car not found.")
})
public ResponseEntity<Car> getCarByColor(@RequestParam String color) {
    return ResponseEntity.ok(testService.getCarByColor(color));
}

步骤2：清理模型类的冗余注解 #

确保Car类只使用V2的注解，去掉V3的@Schema：

package com.example.demo.model;
import javax.validation.constraints.Max;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel(value = "Car", description = "The model for car")
@Data
public class Car {
    @ApiModelProperty(notes = "Car ID.", example = "12345", required = false, position = 0)
    private Long id;
    @ApiModelProperty(notes = "Car name.", example = "Suzuki Swift 2020", required = true, position = 1)
    @NotNull
    @Max(value = 30, message = "Name can only have a maximum length of 30")
    private String name;
    @ApiModelProperty(notes = "Car color.", example = "blue", required = true, position = 2)
    @NotNull
    @Max(value = 30, message = "Color can only have a maximum length of 30")
    @Pattern(regexp = "^(blue|yellow)$", message = "Only blue or yellow color is allowed.")
    private String color;

    public Car(Long id, String name, String color) {
        this.id = id;
        this.name = name;
        this.color = color;
    }
}

方案2：改用纯OAS 3.0注解（推荐，Springfox 3.x更适配OAS3） #

步骤1：重构控制器注解与返回类型 #

完全使用V3注解，同时修正返回类型：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.Parameter;

// ...

@GetMapping(path = "/car", produces = "application/json")
@Operation(summary = "Get car by color.")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "OK.", 
        content = @Content(mediaType = "application/json", 
            schema = @Schema(implementation = Car.class))),
    @ApiResponse(responseCode = "400", description = "Invalid color provided.",
        content = @Content),
    @ApiResponse(responseCode = "404", description = "Car not found.",
        content = @Content)
})
public ResponseEntity<Car> getCarByColor(
    @Parameter(description = "Color of the car.", required = true) @RequestParam String color) {
    return ResponseEntity.ok(testService.getCarByColor(color));
}

步骤2：模型类改用V3注解 #

去掉所有V2注解，只用@Schema：

package com.example.demo.model;
import javax.validation.constraints.Max;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Schema(name = "Car", description = "The model for car")
@Data
public class Car {
    @Schema(description = "Car ID.", example = "12345", required = false, position = 0)
    private Long id;
    @Schema(description = "Car name.", example = "Suzuki Swift 2020", required = true, position = 1)
    @NotNull
    @Max(value = 30, message = "Name can only have a maximum length of 30")
    private String name;
    @Schema(description = "Car color.", example = "blue", required = true, position = 2)
    @NotNull
    @Max(value = 30, message = "Color can only have a maximum length of 30")
    @Pattern(regexp = "^(blue|yellow)$", message = "Only blue or yellow color is allowed.")
    private String color;

    public Car(Long id, String name, String color) {
        this.id = id;
        this.name = name;
        this.color = color;
    }
}

额外注意事项 #

• 确保testService.getCarByColor(color)确实返回Car类型对象，避免类型转换问题。
• Springfox 3.x修改注解后，建议重启应用或者清理缓存，确保注解生效。
• 访问Swagger UI的路径注意：Springfox 3.x默认是/swagger-ui/（末尾带斜杠），别和V2的/swagger-ui.html搞混。

内容的提问来源于stack exchange，提问作者Patrick C.