fix: OpenAPI 接口文档元数据前端输出 base64 字符串导致文档无法显示的问题修复

Spring Boot 4 / Spring Framework 7 中不建议通过 WebMvcConfigurer 手工替换/重建 MVC 的 HttpMessageConverters 列表(相关回调已标记废弃且计划移除)。此类只负责提供全局 JsonMapper配置,保持 Spring Boot 默认 converters(例如 ByteArrayHttpMessageConverter)不被误删。出现的接口文档 Base64 问题根因:springdoc 的 /v3/api-docs/** 可能以 byte[] 形式输出 JSON。当默认的 ByteArrayHttpMessageConverter 缺失时,byte[] 会被 Jackson 当作普通对象序列化为Base64 字符串,导致浏览器/Knife4j 看到一整段 "eyJ..."。保持默认 converters + 仅配置 ObjectMapper 是最稳妥的修复方式。
This commit is contained in:
Ray.Hao committed 2026-01-12 11:25:52 +08:00
1 parent 9432448d93
commit 43394dd402
2 files changed
+47 -79

No files matched your search

@@ -0,0 +1,47 @@
package com.youlai.boot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import tools.jackson.databind.cfg.DateTimeFeature;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.module.SimpleModule;
import tools.jackson.databind.ser.std.ToStringSerializer;
import java.math.BigInteger;
import java.text.SimpleDateFormat;
import java.util.TimeZone;
/**
* Jackson 全局序列化配置
*
* <p>本项目的统一序列化策略:
* <br>- 统一时区 GMT+8 统一日期格式 yyyy-MM-dd HH:mm:ss
* <br>- Long/BigInteger 序列化为字符串,避免前端精度丢失
* <br>- 禁用 WRITE_DATES_AS_TIMESTAMPS,避免日期输出为时间戳</p>
*
* @author Ray.Hao
* @since 2026/1/12
*/
@Configuration
public class JacksonConfig {
/**
* 全局 JsonMapper
*
* <p>由 Spring Boot 自动装配到 Jackson 相关的 HttpMessageConverter 中,作为全局 JSON 序列化/反序列化
* 行为的唯一入口。</p>
*/
@Bean
public JsonMapper objectMapper() {
return JsonMapper.builder()
.disable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS)
.defaultDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"))
.defaultTimeZone(TimeZone.getTimeZone("GMT+8"))
.addModule(new SimpleModule()
.addSerializer(Long.class, ToStringSerializer.instance)
.addSerializer(BigInteger.class, ToStringSerializer.instance)
)
.build();
}
}