解决springdoc-openapi返回Base64编码问题的技术方案

问题背景

在使用springdoc-openapi为Spring Boot项目生成API文档时，开发者可能会遇到一个奇怪的现象：访问/v3/api-docs接口返回的不是预期的JSON文档，而是一个Base64编码的字符串。这种情况通常发生在项目自定义了HTTP消息转换器(HttpMessageConverter)配置时。

问题根源分析

这个问题的根本原因在于Spring MVC的消息转换器链配置不当。当开发者自定义WebMvcConfigurer并重写configureMessageConverters方法时，如果没有正确处理字节数组类型的转换器，就会导致springdoc-openapi生成的文档被错误地转换为Base64编码。

Spring MVC在处理响应时，会按照消息转换器列表的顺序寻找第一个能够处理当前响应类型的转换器。如果自定义配置中没有包含合适的ByteArrayHttpMessageConverter，或者它的顺序不正确，就可能导致文档内容被错误的转换器处理。

解决方案

方案一：添加ByteArrayHttpMessageConverter

最简单的解决方案是在自定义的消息转换器列表中添加ByteArrayHttpMessageConverter，并确保它位于列表的前面位置：

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    // 添加字节数组转换器
    converters.add(new ByteArrayHttpMessageConverter());
    
    // 添加其他自定义转换器
    Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
    // ... 其他builder配置
    ObjectMapper objectMapper = builder.build();
    converters.add(new MappingJackson2HttpMessageConverter(objectMapper));
}

方案二：自定义字节数组转换器

如果需要更精细的控制，可以自定义一个专门处理字节数组到字符串的转换器：

public class ByteArrayToStringConverter extends AbstractHttpMessageConverter<byte[]> {
    public ByteArrayToStringConverter() {
        super(MediaType.APPLICATION_JSON);
    }

    @Override
    protected boolean supports(Class<?> clazz) {
        return byte[].class.isAssignableFrom(clazz);
    }

    @Override
    protected byte[] readInternal(Class<? extends byte[]> clazz, 
                                 HttpInputMessage inputMessage) throws IOException {
        return inputMessage.getBody().readAllBytes();
    }

    @Override
    protected void writeInternal(byte[] bytes, 
                                HttpOutputMessage outputMessage) throws IOException {
        String output = new String(bytes, StandardCharsets.UTF_8);
        outputMessage.getBody().write(output.getBytes());
    }
}

然后在配置类中使用这个自定义转换器：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(0, new ByteArrayToStringConverter());
        // 添加其他转换器...
    }
}

最佳实践建议

1. 转换器顺序很重要：确保字节数组转换器在列表中的位置靠前，这样Spring会优先使用它来处理/v3/api-docs的响应。

2. 保留默认转换器：在自定义配置时，考虑调用super.addDefaultHttpMessageConverters(converters)来保留Spring Boot的默认转换器配置。

3. 测试验证：配置完成后，务必通过浏览器或Postman等工具访问/v3/api-docs接口，确认返回的是格式正确的JSON文档而非Base64编码。

4. 兼容性考虑：如果项目同时使用了FastJson和Jackson，需要特别注意它们之间的兼容性问题，避免转换器冲突。

总结

springdoc-openapi返回Base64编码的问题通常是由于消息转换器配置不当引起的。通过合理配置ByteArrayHttpMessageConverter或自定义字节数组转换器，可以确保API文档能够正确返回JSON格式。理解Spring MVC的消息转换机制对于解决这类问题非常重要，也能帮助开发者在自定义Web配置时避免类似问题的发生。