Swagger 参数文档化

3

当前状态:

我的控制器中有两个方法,根据传递的参数获取数据。 代码如下:

@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文档不符合我的期望。

enter image description here

enter image description here

问题

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

这是我的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
    }
5个回答

3

1
你说得对。我已经添加了自己的答案,这更像是一个解决方法。感谢你的帮助。 - Safari137

1
根据此线程所述:
Swagger规范不允许请求参数不同的多个端点。但是,您可以使用实验性功能docket#enableUrlTemplates(true)绕过此限制。请注意这是实验性的功能。还请升级到2.7.0版本。

不行-链接只是补充内容。引语就是答案。答案基本上是不允许的,这很好作为答案。 - Wai Ha Lee

1

请看Tobias Raski的回答,了解更多关于为什么存在这个问题的内容。

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

总之,有一个实验性的UI可以解决这个问题。当未来的修复发布时,这可能最终变得不相关。


0

在您的 @RequestMapping 注释中移除 'params' 属性,您的代码仍将可用。


那会破坏控制器。这两种方法将具有相同的映射。唯一区别它们的是@RequestMapping中的params部分。 - Safari137
那么,删除getSamplesByIdAndCost方法,将Size Requestparam设置为可选的(required=false)呢? - gtonic
将它们分开的主要目的是因为它们各自的文档非常独特。 - Safari137

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

点击这里查看更多。


网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接