Got "Ambiguous handler methods mapped for '/v3/api-docs'" after migrating from SpringFox to SpringDoc

Question

Using Spring Boot 2.4.5 and IntelliJ 2021.2. After migrated

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

to

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.10</version>
</dependency>

Everytime I access http://localhost:8080/swagger-ui.html. The page says:

Fetch errorundefined /v3/api-docs

and when I check the logs:

java.lang.IllegalStateException: Ambiguous handler methods mapped for '/v3/api-docs': {public org.springframework.http.ResponseEntity springfox.documentation.oas.web.OpenApiControllerWebMvc.getDocumentation(java.lang.String,javax.servlet.http.HttpServletRequest), public java.lang.String org.springdoc.webmvc.api.OpenApiWebMvcResource.openapiJson(javax.servlet.http.HttpServletRequest,java.lang.String) throws com.fasterxml.jackson.core.JsonProcessingException} at org.springframework.web.servlet.handler.AbstractHandlerMethodMapping.lookupHandlerMethod(AbstractHandlerMethodMapping.java:426) at org.springframework.web.servlet.handler.AbstractHandlerMethodMapping.getHandlerInternal(AbstractHandlerMethodMapping.java:377) at org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping.getHandlerInternal(RequestMappingInfoHandlerMapping.java:125) at org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping.getHandlerInternal(RequestMappingInfoHandlerMapping.java:67) at org.springframework.web.servlet.handler.AbstractHandlerMapping.getHandler(AbstractHandlerMapping.java:498) at org.springframework.web.servlet.DispatcherServlet.getHandler(DispatcherServlet.java:1257) at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1039) 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)

There is seemingly a duplicated handler method with the same path from SpringFox and how would I remove the one from SpringFox (It no longer exist in my pom file)?

Answer 1

Remove the swagger dependencies, springfox dependencies. Only adding openapi dependencies are enough.

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.6.6</version>
    </dependency>

Answer 2

Do you still have both dependencies? I had the same problem, except with webflux. After some digging I discovered the following:

• springdoc-openapi-webflux-core-1.5.10: OpenAPIWebfluxResource.class
• springfox-oas-3.0.0: OpenAPIControllerWebFlux.class

Both these classes create handlers for the "/v3/api-docs" mapping. They are incompatible as is warned by the springdoc documentation:

https://springdoc.org/#differentiation-to-springfox-project

11.35. Differentiation to Springfox project

• OAS 3 was released in July 2017, and there was no release of springfox to support OAS 3. springfox covers for the moment only swagger 2 integration with Spring Boot. The latest release date is June 2018. So, in terms of maintenance there is a big lack of support lately.
• ...
• We rely on on swagger-annotations and swagger-ui only official libraries.
• ...

11.36. How do I migrate to OpenAPI 3 with springdoc-openapi

• There is no relation between springdoc-openapi and springfox.If you want to migrate to OpenAPI 3:
• Remove all the dependencies and the related code to springfox
• Add springdoc-openapi-ui dependency
• If you don’t want to serve the UI from your root path or there is a conflict with an existing configuration, you can just change the following property:

springdoc.swagger-ui.path=/you-path/swagger-ui.html