Repository navigation
Bump springdoc-openapi to 2.7.0 for Spring Boot 3.4 (fixes 500 on /v3/api-docs) - #5
Merged
tdaly61 merged 2 commits intoAug 24, 2026
Conversation
springdoc 2.6.0 is built for Spring Boot 3.3 / Spring Framework 6.1. It calls
ControllerAdviceBean(Object), which Spring Framework 6.2 removed, so on Spring
Boot 3.4 a GET /v3/api-docs fails with:
java.lang.NoSuchMethodError: 'void
org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'
The call sits inside a filter over the controller-advice list, so it only runs
when the application has at least one @ControllerAdvice bean. Apps without one
serve their OpenAPI document fine on 2.6.0, which is why this went unnoticed.
2.7.0 is the first release that supports Spring Boot 3.4, and it keeps emitting
OpenAPI 3.0.1. Later 2.8.x releases fix the same bug but switch the document to
OpenAPI 3.1.0, which is a behaviour change and not needed here.
tdaly61
approved these changes
Aug 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
One line in
gradle.properties:springdocVersionfrom 2.6.0 to 2.7.0 (plus a comment explaining why it must not go back).Why
springdoc 2.6.0 is built for Spring Boot 3.3 / Spring Framework 6.1. It calls
ControllerAdviceBean(Object), a constructor that Spring Framework 6.2 removed — and 6.2 is what Spring Boot 3.4.4 ships. So on our stack a request to/v3/api-docsfails with:The BOM pins Spring Boot 3.4.4 and springdoc 2.6.0 next to each other, and those two versions cannot work together.
The broken call sits inside a filter over the list of controller-advice beans, so it only runs when the application has at least one
@ControllerAdvicebean. Applications without one serve their OpenAPI document fine even on 2.6.0, which is why this went unnoticed for a while.How urgent is this
Not urgent. No payment path is affected. Everything else works: the apps start normally, the Camel routes come up, the Zeebe workers register, the REST endpoints that carry actual traffic all respond. The only thing that breaks is the OpenAPI documentation endpoint (
/v3/api-docs, and the Swagger UI that reads it). So this is a developer-facing problem, not a production incident — it can go in whenever it suits the release flow.It is worth fixing in the BOM rather than per repo, because the components that work today do so only because they have no advice bean. They would start failing the day someone adds an exception mapper.
Why 2.7.0 and not 2.8.6
2.8.6 is the latest release and it fixes the bug just as well. I tested it too. But from 2.8.x springdoc changes the document it emits from OpenAPI 3.0.1 to OpenAPI 3.1.0. I verified that on the channel connector: 2.8.6 emits
"openapi":"3.1.0", 2.7.0 keeps"openapi":"3.0.1".That version bump in the document is a real behaviour change for anyone generating client code from it, and it is not needed to fix this bug. 2.7.0 is the smallest change that makes the stack correct, so it keeps this PR to one thing. Moving to 2.8.x can be a separate, deliberate decision later.
Note on the Swagger UI in connector-channel
While testing I found that in
connector-channel/swagger-ui/index.htmlreturns 500 even with springdoc fixed. That is a different, pre-existing problem and is not addressed here:WebMvcConfig extends WebMvcConfigurationSupport, which turns off Spring Boot's MVC auto-configuration, so the webjar static resources are never mapped (No mapping for GET /swagger-ui/index.html) and the catch-all advice turns that 404 into a 500. Worth a separate issue if the UI is wanted there — the/v3/api-docsdocument itself is correct after this change.