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)?

Peraza

Look around for Springfox dependencies by performing a dependency analysis and get rid of them. You seem to have removed springfox-boot-starter but from what I recall, there should be another Springfox dependency for the Swagger-UI – Deuno

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>

Cuba

This worked. Thanks. I had the dependency springfox-boot-starter in my project and removing that worked. – Gloaming

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

Fallen

Answer 3

You can try like this: springdoc-openapi-ui + springfox-swagger2, instead of springfox-boot-starter

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.5.4</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
     <version>3.0.0</version>
</dependency>

Recognize

Answer 4

This can be solved by adding a new controller (I named it

HomeController) with this mapping.
@GetMapping(value = {"/", "/swagger-ui", "/swagger-ui+html"})
public String index() {
    return "redirect:/swagger-ui/index.html";
}

Garrott

Answer 5

i just change /v3/api-docs to /v2/api-docs and it work

Scrutator

Please update with your spring boot or/and springdoc version – Speechmaking

Answer 6

I wrote SwaggerFilter

@Component
@Order(1)
public class SwaggerFilter implements Filter {
   @Override
   public void doFilter(
           ServletRequest request,
           ServletResponse response,
           FilterChain chain) throws IOException, ServletException {

       HttpServletRequest req = (HttpServletRequest) request;

       if (req.getRequestURI().equals("/v3/api-docs")) {
           RequestDispatcher dispatcher = ((HttpServletRequest) request).getSession().getServletContext()
                .getRequestDispatcher("/v2/api-docs");
           dispatcher.forward(req, response);
       } else {
           chain.doFilter(request, response);
       }
   }
}

Cithara

Thanks a lot for this answer. Could you please explain a bit in your words what the code is doing? – Trotman

Its java filter which forward to /v2/api-docs if condition true. Its java basic – Cithara