Spring Boot集成Swagger/OpenAPI失败，请求API定义返回500错误

问题现象 #

• Spring Boot应用运行正常，但访问http://localhost:8080/swagger-ui/index.html时，页面提示Failed to load API definition
• 调用/services-mgrs-api-docs接口返回500状态码

错误日志 #

java.lang.NoSuchMethodError: 'io.swagger.v3.oas.models.media.ComposedSchema io.swagger.v3.oas.models.media.ComposedSchema.addOneOfItem(io.swagger.v3.oas.models.media.Schema)'
    at org.springdoc.core.SpringDocAnnotationsUtils.mergeSchema(SpringDocAnnotationsUtils.java:207)
    at org.springdoc.core.GenericResponseService.lambda$buildApiResponses$6(GenericResponseService.java:519)
    at java.base/java.util.Spliterators$ArraySpliterator.forEachRemaining(Spliterators.java:992)
    at java.base/java.util.stream.ReferencePipeline$Head.forEach(ReferencePipeline.java:762)
    at org.springdoc.core.GenericResponseService.buildApiResponses(GenericResponseService.java:519)
    at org.springdoc.core.GenericResponseService.buildApiResponses(GenericResponseService.java:349)
    at org.springdoc.core.GenericResponseService.build(GenericResponseService.java:160)
    at org.springdoc.api.AbstractOpenApiResource.calculatePath(AbstractOpenApiResource.java:460)
    at org.springdoc.api.AbstractOpenApiResource.calculatePath(AbstractOpenApiResource.java:604)
    at org.springdoc.webmvc.api.OpenApiResource.calculatePath(OpenApiResource.java:215)
    at org.springdoc.webmvc.api.OpenApiResource.getPaths(OpenApiResource.java:162)
    at org.springdoc.api.AbstractOpenApiResource.getOpenApi(AbstractOpenApiResource.java:323)
    at org.springdoc.webmvc.api.OpenApiResource.openapiJson(OpenApiResource.java:123)
    at org.springdoc.webmvc.api.OpenApiWebMvcResource.openapiJson(OpenApiWebMvcResource.java:107)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.base/java.lang.reflect.Method.invoke(Method.java:568)
    at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:205)
    at org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:150)
    at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:117)
    at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:895)
    at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:808)
    at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)
    at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1067)
    at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:963)
    at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006)
    at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:898)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:655)
    at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:764)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:227)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.springframework.boot.actuate.web.trace.servlet.HttpTraceFilter.doFilterInternal(HttpTraceFilter.java:88)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at io.opentelemetry.instrumentation.spring.webmvc.WebMvcTracingFilter.doFilterInternal(WebMvcTracingFilter.java:35)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.springframework.boot.actuate.metrics.web.servlet.WebMvcMetricsFilter.doFilterInternal(WebMvcMetricsFilter.java:96)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:189)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:162)
    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:197)
    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:97)
    at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:541)
    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:135)
    at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92)
    at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:78)
    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:360)
    at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:399)
    at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)
    at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:890)
    at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1787)
    at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
    at org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191)
    at org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659)
    at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
    at java.base/java.lang.Thread.run(Thread.java:833)

根因分析 #

同时引入了SpringFox（Swagger 2的旧实现）和SpringDoc（OpenAPI 3的官方兼容实现），两个框架底层依赖的Swagger/OpenAPI核心库版本不一致：

• SpringDoc 1.6.4依赖的Swagger v3核心库包含ComposedSchema.addOneOfItem()方法
• SpringFox依赖的低版本Swagger v3库没有该方法
• Maven构建时优先引入了SpringFox的低版本库，导致SpringDoc调用方法时抛出NoSuchMethodError

修复步骤 #

1. 移除所有SpringFox依赖：从pom.xml中删除以下依赖：

   • springfox-swagger2
   • springfox-swagger-ui
   • springfox-oas

2. 保留并适配SpringDoc依赖：仅保留springdoc-openapi-ui，确保版本与你的Spring Boot版本匹配（1.6.4对应Spring Boot 2.6.x）

3. 统一Swagger注解依赖：删除手动指定的swagger-annotations依赖，让SpringDoc自动管理其版本，避免冲突

4. 清理缓存并重建：

   • 执行mvn clean install清理Maven缓存并重新构建项目
   • 重启Spring Boot应用

修改后的pom.xml示例 #

<!-- 仅保留SpringDoc OpenAPI UI依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.4</version>
</dependency>
<!-- 保留jaxb-api（如果业务需要） -->
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
</dependency>

验证方法 #

• 重启应用后访问http://localhost:8080/swagger-ui/index.html，确认API定义能正常加载
• 调用/services-mgrs-api-docs接口（或默认的/v3/api-docs），确认返回200状态码和正确的OpenAPI JSON文档

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