springdoc-openapi项目中的二进制响应问题分析与解决

问题背景

在使用springdoc-openapi 2.4.0与Spring Boot 3.2.1集成的项目中，开发人员遇到了一个特殊问题：当访问/api-docs接口时，预期返回的JSON格式的API文档变成了二进制数据。这种情况在多个Web应用中出现，但解决方案却不尽相同。

问题现象

正常情况下，访问springdoc-openapi的/api-docs接口应该返回结构化的JSON数据，包含API的详细描述信息。但在问题项目中，返回的却是无法直接阅读的二进制内容，这显然不符合预期行为。

根本原因分析

经过深入调查，发现问题与Spring MVC的消息转换器配置密切相关，特别是MappingJackson2HttpMessageConverter和ByteArrayHttpMessageConverter之间的交互关系。

1. 消息转换器冲突：Spring MVC在处理响应时会根据内容类型选择合适的消息转换器。当多个转换器都能处理相同类型的内容时，可能会出现优先级问题。

2. 转换器配置影响：在某些项目中，移除MappingJackson2HttpMessageConverter可以解决问题，这表明该转换器可能干扰了ByteArrayHttpMessageConverter的正常工作。

3. 配置差异：不同项目中的解决方案不同，说明问题可能与具体的Spring MVC配置方式有关。XML配置和注解配置可能存在细微差别。

解决方案

针对这个问题，可以尝试以下几种解决方案：

方案一：调整消息转换器顺序

在Spring MVC配置中，明确指定消息转换器的顺序，确保JSON转换器优先于二进制转换器：

<mvc:annotation-driven>
    <mvc:message-converters register-defaults="true">
        <bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter"/>
        <bean class="org.springframework.http.converter.StringHttpMessageConverter"/>
    </mvc:message-converters>
</mvc:annotation-driven>

方案二：自定义转换器配置

对于使用RequestMappingHandlerAdapter显式配置的项目，可以尝试以下方式：

<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
    <property name="messageConverters">
        <list>
            <ref bean="jackson2HttpMessageConverter"/>
            <ref bean="stringMessageConverter"/>
        </list>
    </property>
</bean>

方案三：检查内容协商配置

确保内容协商策略正确配置，优先返回JSON格式：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer.defaultContentType(MediaType.APPLICATION_JSON);
    }
}

最佳实践建议

1. 统一配置方式：尽量使用同一种方式配置消息转换器，避免混合使用XML和Java配置。

2. 明确转换器顺序：当注册多个消息转换器时，明确指定它们的顺序，确保最常用的转换器优先。

3. 测试验证：在修改配置后，应全面测试API文档接口和其他API接口，确保所有功能正常。

4. 版本兼容性检查：确认springdoc-openapi版本与Spring Boot版本的兼容性，必要时升级到最新稳定版。

总结

springdoc-openapi项目中出现的二进制响应问题通常源于消息转换器的配置不当。通过合理调整转换器顺序和内容协商策略，可以确保API文档接口返回正确的JSON格式数据。开发人员在集成第三方库时，应特别注意框架底层组件的交互关系，避免类似问题的发生。