Spring WebFlux集成springdoc-openapi时Swagger UI部分加载问题

这类静态资源只返回部分内容的问题，在WebFlux场景下基本都是以下几类原因，按出现概率从高到低排列：

• 响应内存缓冲区阈值配置过低
  Spring WebFlux 默认基于Netty处理请求响应，默认的编解码内存缓冲区上限仅为256KB，而swagger-ui-bundle.js单文件大小通常在1MB以上，当响应内容大小超过阈值时，Netty不会抛出显式异常，会直接将已经写入缓冲区的部分内容返回，导致JS/CSS截断。
  调整配置即可修复，示例配置：

  spring:
    codec:
      max-in-memory-size: 10MB
  

  如果自定义了Netty服务端配置，还需要同步检查HTTP响应分块大小的相关配置，不要设置过小的单块阈值。

• 自定义WebFilter/全局响应处理器错误截断响应流
  大部分项目会自定义全局响应包装、响应日志打印、加解密等过滤器，如果这类过滤器没有排除Swagger相关路径（/swagger-ui/**、/webjars/**、/v3/api-docs/**），且在处理响应流时逻辑有误——比如仅读取了第一个DataBuffer就直接写回响应，没有聚合Flux流中的所有数据块，就会直接截断静态资源内容。
  排查时可以临时注释所有自定义WebFilter，如果静态资源恢复正常，再逐个给过滤器添加Swagger路径白名单，或者修复流聚合逻辑：处理响应时需要用Flux<DataBuffer>收集所有数据块拼接完成后再写回，不能只取首个数据块返回。

• 前置代理层截断响应
  如果服务前端挂载了Nginx、API网关等代理组件，代理层的响应缓冲区配置过小、HTTP版本不兼容、压缩配置冲突都可能导致静态资源被截断。排查时可以绕过代理，直接访问后端服务的监听端口测试静态资源：如果直连时资源大小完整，问题就出在代理层，对应调大代理缓冲区、调整压缩配置即可。

• 版本不兼容
  springdoc-openapi和Spring Boot版本有严格的对应关系：Spring Boot 2.x系列需要搭配1.x版本的springdoc，Spring Boot 3.x系列必须搭配2.x以上版本的springdoc。版本不匹配时，静态资源路由的注册逻辑、资源解析逻辑会存在异常，可能出现未读取完资源文件就提前关闭响应流的问题，对照适配关系调整依赖版本即可。

快速排查步骤 #

1. 直连后端端口访问静态资源，对比响应头Content-Length和本地依赖jar包内对应资源的实际大小，先区分是后端问题还是代理层问题
2. 排除所有自定义过滤器对Swagger路径的拦截，验证是否是过滤器逻辑导致
3. 调大编解码内存缓冲区配置验证
4. 核对依赖版本匹配关系

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