Issue with Swagger UI

[PascalLugon]

Hello,

After migrating my application to SpringBoot 3.5.5, SpringCloud 2025.0.0 and CIB Seven 2.1.0-alpha, the Swagger UI is no more displayed. In fact the URL /v3/api-docs/public if returning a 500 error with the exception:

java.lang.NoSuchMethodError: 'java.lang.String io.swagger.v3.oas.annotations.media.Schema.$dynamicRef()' at io.swagger.v3.core.util.AnnotationsUtils.getSchemaFromAnnotation(AnnotationsUtils.java:674)

On my main DEV branch using Camunda 7.23.0, I don't have this issue and the Swagger UI is correctly displayed.

Does anyone have the same issue?

BR
Pascal

[Rafael-Bessa]

Hello Pascal,

I noticed your issue is a classic and very common dependency conflict specific to the Spring Boot 3.x and OpenAPI ecosystem. The error, java.lang.NoSuchMethodError: 'java.lang.String io.swagger.v3.oas.annotations.media.Schema.$dynamicRef()', occurs because a class (likely from one of your other dependencies) was compiled against a newer version of the OpenAPI library (io.swagger.v3) than the one that is actually loaded at runtime.

This is a classpath issue, not a code bug.

The Recommended Solution: Centralized Dependency Management

The most professional and stable solution is to ensure that only the official Springdoc starter is responsible for managing all the transitive OpenAPI dependencies.

Here is the precise course of action:

1. Remove Explicit Dependencies: First, check your build file (pom.xml or build.gradle) and remove any explicit dependencies on io.swagger.v3 components (like swagger-annotations or swagger-models). Let Springdoc manage these versions.

2. Verify the Correct Starter: Ensure you are using the correct starter for Spring Boot 3.x. The dependency should be:

   • Maven: <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   • Gradle: implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui'

3. Check Version Compatibility (Crucial): Since you are using Spring Boot 3.5.5, you must use a recent version of the springdoc-openapi library that is guaranteed to be compatible with Spring Framework 6.2+ (which is used by Boot 3.5.5). Look up the latest stable 2.x.x version (e.g., 2.7.0 or 2.8.0, or higher) and explicitly set it:

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.X.X</version> </dependency>

If the issue persists, your next step should be to run a dependency analysis (like mvn dependency:tree) to manually identify which external library is transitively pulling in an older, incompatible version of io.swagger.v3. You may then need to add an exclusion to block the wrong version.

This approach eliminates the root cause and provides the most stable long-term fix.

Hope this gets your Swagger UI working! If this fixes your 500 error, please mark this comment as the correct answer.

[PascalLugon]

Rafael,
Thanks for the detailed answer.
You were right with the dependency conflict. But after the analyze of the dependencies tree, it appears that the cibseven-bpm-spring-boot-starter-webapp dependency is loading the conflicting dependency:

    <dependency>
        <groupId>org.cibseven.bpm.springboot</groupId>
        <artifactId>cibseven-bpm-spring-boot-starter-webapp</artifactId>
        <exclusions>
            <exclusion>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-annotations-jakarta</artifactId>
            </exclusion>
        </exclusions>
    </dependency>

So I've just added the exclusion and Swagger UI is now working.
BR
Pascal