当前位置：首页 > news >正文

Spring Boot 自定义 HttpMessageConverter 导致 Swagger 文档无法访问的解决方案

news 来源：原创 2025/5/18 14:37:53

问题背景

在 Spring Boot 项目中，我们经常需要自定义 HttpMessageConverter 来处理 JSON 序列化，比如将 Long 类型转换为 String 以避免前端 JavaScript 的精度丢失问题。然而，当我们直接覆盖默认的 MappingJackson2HttpMessageConverter 时，可能会导致 Swagger 文档无法正常访问，返回空白页面或 JSON 解析错误。

问题复现

以下是一个典型的自定义 HttpMessageConverter 配置：

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
    ObjectMapper objectMapper = new ObjectMapper();
    SimpleModule simpleModule = new SimpleModule();
    simpleModule.addSerializer(BigInteger.class, ToStringSerializer.instance);
    simpleModule.addSerializer(Long.class, ToStringSerializer.instance);
    simpleModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
    objectMapper.registerModule(simpleModule);
    objectMapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
    jackson2HttpMessageConverter.setObjectMapper(objectMapper);
    converters.add(0, jackson2HttpMessageConverter); // 添加到首位
}

问题现象：

访问 http://localhost:8080/swagger-ui.html 时，页面无法加载或显示异常。
直接访问 http://localhost:8080/v3/api-docs/default 时，返回的 JSON 数据可能不符合 Swagger 的预期格式。

问题原因

覆盖默认转换器
Spring Boot 默认会注册 MappingJackson2HttpMessageConverter，用于 JSON 序列化。当我们手动添加自定义转换器并放在首位（converters.add(0, ...)），会导致 Swagger 使用的默认转换器被跳过。
ObjectMapper 配置冲突
Swagger 依赖特定的 ObjectMapper 配置来生成 API 文档。如果我们修改了 ObjectMapper（如 Long 转 String），可能会破坏 Swagger 的 JSON 结构，导致文档无法正确渲染。

解决方案

方案 1：仅修改现有的 Jackson 转换器（推荐）

避免覆盖默认转换器，而是找到已存在的 MappingJackson2HttpMessageConverter 并修改其 ObjectMapper：

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    for (HttpMessageConverter<?> converter : converters) {
        if (converter instanceof MappingJackson2HttpMessageConverter) {
            ObjectMapper objectMapper = ((MappingJackson2HttpMessageConverter) converter).getObjectMapper();
            configureObjectMapper(objectMapper);
            return;
        }
    }
    // 如果没找到，再添加新的转换器
    addNewJacksonConverter(converters);
}

private void configureObjectMapper(ObjectMapper objectMapper) {
    SimpleModule module = new SimpleModule();
    module.addSerializer(BigInteger.class, ToStringSerializer.instance);
    module.addSerializer(Long.class, ToStringSerializer.instance);
    module.addSerializer(Long.TYPE, ToStringSerializer.instance);
    objectMapper.registerModule(module);
    objectMapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
}

private void addNewJacksonConverter(List<HttpMessageConverter<?>> converters) {
    MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
    ObjectMapper objectMapper = new ObjectMapper();
    configureObjectMapper(objectMapper);
    converter.setObjectMapper(objectMapper);
    converters.add(converter);
}

方案 2：动态判断请求路径，Swagger 请求走默认转换器

如果必须添加新的 HttpMessageConverter，可以动态判断请求路径，让 Swagger 请求仍然使用默认转换器：

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    ObjectMapper customObjectMapper = new ObjectMapper();
    SimpleModule module = new SimpleModule();
    module.addSerializer(BigInteger.class, ToStringSerializer.instance);
    module.addSerializer(Long.class, ToStringSerializer.instance);
    module.addSerializer(Long.TYPE, ToStringSerializer.instance);
    customObjectMapper.registerModule(module);
    customObjectMapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);

    MappingJackson2HttpMessageConverter customConverter = new MappingJackson2HttpMessageConverter(customObjectMapper) {
        @Override
        public boolean canWrite(Class<?> clazz, MediaType mediaType) {
            // 如果是 Swagger 请求，则不使用自定义转换器
            ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            if (attrs != null) {
                String path = attrs.getRequest().getRequestURI();
                if (path.startsWith("/v3/api-docs") || path.startsWith("/swagger-ui")) {
                    return false; // 让默认转换器处理
                }
            }
            return super.canWrite(clazz, mediaType);
        }
    };
    converters.add(0, customConverter);
}

方案对比

方案	优点	缺点
修改现有转换器	兼容性最好，不影响 Swagger	需要确保默认转换器存在
动态路径判断	灵活控制不同请求的转换逻辑	需要依赖 `RequestContextHolder`