Swagger 参数文档

Swagger Param Documentation

当前状态:

我的控制器中有两种方法可以根据传递的参数获取数据。代码:

@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;
    }
}

一切正常,但 swagger 文档不是我所期望的。

问题

有没有办法从请求中删除 {?size,cost} URL?

这是我的 Docket 信息:

@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
    }

删除 @RequestMapping 注释中的 'params' 属性,您的代码仍然有效。

Swagger 规范不支持基于查询字符串的同一路径的多个文档,因此 swagger-ui.

不支持

您通过设置 enableUrlTemplating(true) 启用的功能似乎是 springfox 中的孵化功能,但目前无法使用 swagger-ui。

相关讨论可以在这里找到:

目前看来,您要么不得不忍受在 swagger 中看起来很奇怪的路径-ui,要么必须合并您的文档。

查看 Tobias Raski 的回答以了解有关此问题存在原因的更多信息。

有一个解决方法。您可以在此处查看一些详细信息:https://github.com/springfox/springfox/issues/1484

总而言之,有一个实验性的 UI 解决了这个问题。当未来的修复出现时,这可能最终是无关紧要的。

根据this thread

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

你可以改变maven pom

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

使用springfox-swagger-ui-rfc6570代替springfox-swagger-ui

点击here查看更多。