Swagger Param Documentation

Question

Current State:

I have two methods in my controller to get data based on what parameters are passed. The code:

@RestController
@RequestMapping("/samples")
public class SampleController {

    @RequestMapping(value = "/{id}", params = {"cost"}, method = RequestMethod.GET)
    public String getSamplesByIdAndCost(@PathVariable String id, @RequestParam(value = "cost") String cost) {
        return "result";
    }

    @RequestMapping(value = "/{id}", params = {"cost", "size"}, method = RequestMethod.GET)
    public String getSamplesByIdCostAndSize(@PathVariable String id, @RequestParam(value = "cost") String cost,
                                        @RequestParam(value = "size") String size) {
    return "ID : " + id + " / COST : " + cost + " / SIZE : " + size;
    }
}

Everything works fine, but the swagger documentation is not what I expected.

Question

Is there a way to remove {?size,cost} from the Request URL?

Here is my Docket info:

@Bean
    public Docket myApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .directModelSubstitute(LocalDate.class,
                        String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .alternateTypeRules(
                        newRule(typeResolver.resolve(DeferredResult.class,
                                typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
                                typeResolver.resolve(WildcardType.class)))
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET,
                        newArrayList(new ResponseMessageBuilder()
                                .code(500)
                                .message("500 message")
                                .responseModel(new ModelRef("Error"))
                                .build()))
                .enableUrlTemplating(true);

    }

    @Autowired
    TypeResolver typeResolver;

    @Bean
    UiConfiguration uiConfig() {
        return new UiConfiguration(
                "validatorUrl",// url
                "none",       // docExpansion          => none | list
                "alpha",      // apiSorter             => alpha
                "schema",     // defaultModelRendering => schema
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS,
                false,        // enableJsonEditor      => true | false
                true);        // showRequestHeaders    => true | false
    }

Answer 1

Multiple documentations for the same path based on query strings is not something that is supported by Swagger spec and therefore not by swagger-ui.

What you have enabled by setting enableUrlTemplating(true) appears to be an incubation feature in springfox but won't work as of now with swagger-ui.

Relevant discussion can be found here:

• https://github.com/swagger-api/swagger-ui/issues/1665
• https://github.com/springfox/springfox/issues/866

For now it seem like you either have to live with paths looking weird in the swagger-ui, or you have to merge your documentation.