Support for multiple endpoints with the same paths that rely on @RequestMapping.param

[ilya40umov]

I'm currently on version 2.6.1 and facing a problem with Swagger UI essentially swallowing all but one Spring REST endpoints that share the same path.
E.g.

@Api("search")
@RestController
@RequestMapping("/v1/search")
public class SearchController {

    @GetMapping(path = "items", params = "name")
    @ApiOperation(value = "Find items by name", response = ItemSearchResponse.class)
    public ResponseEntity<?> searchItemsByName(
            @RequestParam(value = "name") String name) {
       ...
    }

    @GetMapping(path = "items", params = "description")
    @ApiOperation(value = "Find items by description", response = ItemSearchResponse.class)
    public ResponseEntity<?> searchItemsByDescription(
            @RequestParam(value = "description") String description) {
       ...
    }
}

This configuration is telling Spring MVC to call one of two methods depending on which parameter is present in the request URL.
However, Springfox's swagger-ui.html shows only one of the two endpoints. (Moreover, which one of the two will be shown keeps changing from run to run).

I have debugged the code somewhat and this behavior seems to be caused by putting everything into a map inside ServiceModelToSwagger2Mapper.mapApiListings method.

So, I can see two possible solutions for this problem:

1. Fix mapApiListings to somehow differentiate such endpoints (e.g. call them items?name={name} and items?description={description})
2. Allow people to override path using @ApiOperation annotation, so that API developers can fix such cases on their own.

P.S. I know I could kind of work around this problem by using @ApiImplicitParams but that would mean polluting my code with extra redundant information which I really want to avoid.

[dilipkrish]

Swagger spec does not allow multiple endpoints that differ by request params. However you could use the experimental feature to get around it using docket#enableUrlTemplates(true). Keep in mind it is experimental. Also please upgrade to 2.7.0

[ilya40umov]

@dilipkrish Thanks a lot! This feature does solve my problem. Even though, I feel that @ApiOperation should also support overriding the path of an endpoint.

[ilya40umov]

BTW since it's an experimental feature, can I rely on it being there in the future releases or it's still undecided?

[ilya40umov]

And FYI there is no 2.7.0 of io.springfox:springfox-staticdocs which I would have expected to be there along with other deps.

[dilipkrish]

@ilya40umov Its experimental because swagger 2.0 does not support it officially. Will see how that translates to OAS 3.0. But for sure there will be support for it in springfox o/w much of the features people rely on will be unavailable via the specification.

Regarding staticdocs, its not supported any more because there is no point in supporting an older version of swagger2markup. Its easier to use the latest version directly.

[ghost]

Hi @dilipkrish,

I have the same use case here.
Enabling the URL templating results in showing all operations.

My problem now:
The generated request URI is including the specified param like this:
{?myParam}&myParam=myValue

I'd expect that it just adds the param like this: ?myParam=myValue
Is there a possibillity to enable this behaviour?

[dilipkrish]

@Aliceice Thats because you're using an incorrect version of swagger-ui.

[ghost]

@dilipkrish Thanks for the quick reply!
I replaced my swagger-ui dependency with

<dependency>
    <groupId>io.springfox.ui</groupId>
    <artifactId>springfox-swagger-ui-rfc6570</artifactId>
    <version>1.0.0</version>
</dependency>

It seems like it's not being picked up by spring.
Do I need to do anything else?

[dilipkrish]

You need to refresh your browser cache as well

[chengda]

Thanks a lot !

[membersound]

Could you please merge this into master?

[YeJiaL]

Hi @dilipkrish,

I have the same use case here. Enabling the URL templating results in showing all operations.

My problem now: The generated request URI is including the specified param like this: {?myParam}&myParam=myValue

I'd expect that it just adds the param like this: ?myParam=myValue Is there a possibillity to enable this behaviour?

hi，can you tell me how to fix it ?