@RestControllerAdvice
public class ApiResponseAdvice implements ResponseBodyAdvice<Object> {
@Autowired
private ObjectMapper objectMapper;
@Override
public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
return true;
}
@SneakyThrows
@Override
public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
// 处理String类型
if (o instanceof String) {
return objectMapper.writeValueAsString(ResponseData.success(o));
}
// 若是统一返回类型,则不用再此封装
if (o instanceof ResponseData) {
return o;
}
// 排除Swagger相关路径,否则会导致文档读取异常,直接出现文档出现的是Petstore文档
if (serverHttpRequest.getURI().getPath().contains("/v3/api-docs")
|| serverHttpRequest.getURI().getPath().contains("/swagger-ui")) {
return o;
}
return ResponseData.success(o);
}
}
- 这段代码是一个全局响应体处理的切面,用于在Spring
MVC的响应返回之前对数据进行统一处理,以符合特定的响应格式(在这个例子中是ResponseData)。它通过实现ResponseBodyAdvice接口并使用@RestControllerAdvice注解来全局生效。 - 当SpringDoc生成API文档时,它会调用实际的API端点来获取元数据,包括响应类型和模型。你的beforeBodyWrite方法逻辑中,不论原始返回对象是什么类型,最终都会被包装成ResponseData对象(除非它本身就是ResponseData的实例)。这意味着SpringDoc在尝试解析响应模型时,实际上看到的是ResponseData,而非实际API方法原本应直接返回的具体类型。
导致以下问题:
模型失真:API文档中原本应该展示的实际返回类型被统一的ResponseData替代,使得文档无法准确反映每个API的真实返回结构。
Swagger UI显示问题:由于返回类型统一被转换,Swagger UI可能无法正确渲染这些经过二次处理的响应模型,尤其是当直接返回字符串(如JSON字符串)被转换时。
为了解决这个问题同时保持响应体的统一处理,在beforeBodyWrite增加
// 排除Swagger相关路径,否则会导致文档读取异常,直接出现文档出现的是Petstore文档
if (serverHttpRequest.getURI().getPath().contains("/v3/api-docs")
|| serverHttpRequest.getURI().getPath().contains("/swagger-ui")) {
return o;
}