Swagger 参数文档答案

【问题标题】：Swagger Param DocumentationSwagger 参数文档
【发布时间】：2017-01-19 05:39:59
【问题描述】：

当前状态：

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

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

一切正常，但招摇的文档不是我所期望的。

问题

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

这是我的案卷信息：

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

【问题讨论】：

标签： java spring-boot swagger springfox

【解决方案1】：

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

您通过设置 enableUrlTemplating(true) 启用的功能似乎是 springfox 中的一项孵化功能，但目前不适用于 swagger-ui。

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

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

【讨论】：

你是对的。我添加了自己的答案，这更像是一种解决方法。感谢您的帮助。

【解决方案2】：

请参阅 Tobias Raski 的回答，以了解有关此问题存在原因的更多信息。

有一个解决方法。你可以在这里看到一些细节：https://github.com/springfox/springfox/issues/1484

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

【讨论】：

【解决方案3】：

根据this thread：

Swagger 规范不允许请求参数不同的多个端点。但是，您可以通过 docket#enableUrlTemplates(true) 使用实验性功能来解决它。请记住，它是实验性的。也请升级到2.7.0

【讨论】：

否 - 该链接是补充性的。报价就是答案。答案基本上是不允许的，作为答案就好了。

【解决方案4】：

删除@RequestMapping 注解中的“params”属性，您的代码仍然可以工作。

【讨论】：

那会破坏控制器。这两种方法将具有相同的映射。唯一能区分这两者的是@RequestMapping 的参数部分
那么删除 getSamplesByIdAndCost 并将 Size Requestparam 设为可选（required=false）怎么样？
分离它们的主要目的是它们每个的文档都非常独特。

【解决方案5】：

你可以改变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查看更多。

【讨论】：