SpringBoot中SpringFox3.0.0返回Object时ApiResponse示例不显示

方案1：通过@ApiResponse明确指定响应类型并配置示例 #

无需修改接口返回类型，直接在@ApiResponse中通过response属性绑定实际返回的实体类，同时用@Examples配置响应示例。注意使用io.swagger.annotations包下的旧注解：

@GetMapping("/ping")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "成功返回Pong对象", 
        response = Pong.class,
        examples = @Examples(value = {
            @Example(
                value = @ExampleProperty(mediaType = "application/json", value = "{\"message\":\"pong\",\"code\":200}")
            )
        })
    )
})
public Object makePing() {
    return new Pong("pong", 200);
}

方案2：自定义Swagger插件批量处理返回Object的接口 #

如果大量接口存在该问题，可编写自定义ModelAttributePlugin，自动识别返回Object的接口并绑定对应响应模型与示例：

@Component
public class ObjectReturnTypePlugin implements ModelAttributePlugin {
    @Override
    public boolean supports(DocumentationType delimiter) {
        return DocumentationType.SWAGGER_2.equals(delimiter);
    }

    @Override
    public void apply(ModelAttributeContext context) {
        ResolvedType returnType = context.getResolver().resolve(context.getHandlerMethod().getReturnType());
        if (Object.class.equals(returnType.getErasedType())) {
            // 可根据方法名、自定义注解等规则匹配实际响应类
            Method method = context.getHandlerMethod().getMethod();
            if (method.getName().contains("Ping")) {
                // 替换返回类型为Pong
                context.getBuilder().type(context.getResolver().resolve(Pong.class));
                // 添加自定义示例
                context.getBuilder().example("{\"message\":\"pong\",\"code\":200}");
            }
            // 扩展其他接口规则
        }
    }
}

该插件会在Swagger构建文档时自动处理目标接口，无需逐个修改。

方案3：用@ApiImplicitResponse直接配置简单响应示例 #

对于无需关联实体类的简单场景，可直接用@ApiImplicitResponse指定响应示例，无需绑定模型：

@GetMapping("/ping")
@ApiImplicitResponses({
    @ApiImplicitResponse(code = 200, message = "成功返回Pong", 
        examples = @Examples(value = {
            @Example(
                value = @ExampleProperty(mediaType = "application/json", value = "{\"message\":\"pong\",\"code\":200}")
            )
        })
    )
})
public Object makePing() {
    return new Pong("pong", 200);
}

注意事项 #

• 确保使用io.swagger.annotations包下的注解，SpringFox 3对旧注解兼容性更好
• 保留application.properties中的springfox.documentation.swagger.use-model-v3=false配置，禁用OpenAPI v3模型解析避免冲突
• 自定义插件需注册为Spring组件，确保被SpringFox扫描加载

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