Springfox not generating Swagger docs correctly for same operation-endpoint, different query parameters

Question

Springfox doesn't generate correctly the swagger doc for a simple case like this one:

GET /api/departments - Gets all department

GET /api/departments?name=IT - Gets a department with name passed as query parameter

This is the Spring Controller:

@ApiOperation(value = "Gets all departments", notes = "", tags = {"departments"})
@RequestMapping(value="/departments", produces=MediaType.APPLICATION_JSON_VALUE, method=RequestMethod.GET)
public List<Department> getAllDepartments(){
       ...
}

@ApiOperation(value = "Gets a department by name", notes = "", tags = {"departments"})
@RequestMapping(value="/departments", params="name", produces=MediaType.APPLICATION_JSON_VALUE, method=RequestMethod.GET)
public Department getDepartmentByName(@RequestParam String name){
    ...
}

The generated swagger file only contains the GET /api/departments entry, not a trace of the one with the query filter.

Any workaround?

Swagger Config:

@Bean
public Docket departmentsV1Api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.regex("/.*"))                
        .build()
        .apiInfo(new ApiInfo("Departments Rest API","","v1","","","",""))
        .pathMapping("/api")
        .securitySchemes(newArrayList(apiKey()))
        .securityContexts(newArrayList(securityContext()))
        .groupName("departmentsV1");
}

Answer 1

This use case isn't supported by the spec. However you could use the enableUrlTemplating(true) method in your docket to enable rfc6570 support.

There is also an experimental library (springfox-swagger-ui-rfc6570) that can be used as a drop-in replacement for the standard springfox-swagger-ui.

Note: Keep in mind this is in incubation and can change when support is added in the spec.