Spring MVC集成SpringDoc遇序列化异常问题求助

针对你遇到的/v3/api-docs接口重复序列化、Swagger UI页面异常的问题，可按以下步骤排查修复：

1. 调整消息转换器优先级，避免二次序列化 #

非Spring Boot环境下，SpringDoc的OpenApiResource返回的JSON会被Spring MVC默认消息转换器二次处理，导致出现引号包裹或BASE64编码问题。需将SpringDoc专属的消息转换器优先级设为最高：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springdoc.core.converters.SpringDocMessageConverter;

import java.util.List;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Bean
    public SpringDocMessageConverter springDocMessageConverter() {
        return new SpringDocMessageConverter();
    }

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 将SpringDoc转换器放在首位，避免被其他转换器二次序列化
        converters.add(0, springDocMessageConverter());
        // 保留原有Jackson转换器处理自定义接口
        converters.add(new MappingJackson2HttpMessageConverter());
    }
}

2. 排除SpringDoc与项目的Jackson依赖冲突 #

检查你的依赖配置，确保SpringDoc自带的Jackson版本与项目依赖版本一致，避免因版本差异导致序列化异常。如果使用Maven，可添加依赖排除：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>1.8.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 简化OpenApiConfig配置，避免自定义序列化干扰 #

确保你的OpenApiConfig仅负责OpenAPI元信息配置，不要手动绑定自定义ObjectMapper，防止与SpringDoc内部序列化逻辑冲突：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("业务API文档")
                        .version("1.0")
                        .description("系统核心接口描述"));
    }
}

4. 验证DispatcherServlet配置的正确性 #

确保DispatcherServlet加载了SpringDoc相关配置类，避免配置遗漏：

public class DispatcherServletInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class[]{OpenApiConfig.class, WebMvcConfig.class};
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return null;
    }

    @Override
    protected String[] getServletMappings() {
        return new String[]{"/"};
    }
}

5. 调试消息转换器执行流程 #

可在WebMvcConfig中添加日志，确认SpringDoc转换器优先执行：

@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    for (HttpMessageConverter<?> converter : converters) {
        System.out.println("Loaded converter: " + converter.getClass().getName());
    }
}

启动项目后访问/v3/api-docs，查看控制台输出，确认SpringDocMessageConverter是第一个被执行的转换器。

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