如何使用 Swagger 记录 List<CustomObject> 类型的 Spring MVC 请求参数答案

【问题标题】：How to document with Swagger a Spring MVC request param of type List<CustomObject>如何使用 Swagger 记录 List<CustomObject> 类型的 Spring MVC 请求参数
【发布时间】：2019-11-26 09:56:37
【问题描述】：

Spring Boot 2.1.8、Spring Web 5.1.9、Springfox Swagger 2.8.0、Swagger 注释/模型 1.5.14

我的RestController 方法签名如下所示：

    @ApiOperation("List statuses")
    @GetMapping(produces = APPLICATION_JSON_VALUE)
    public ListResult<Status> listStatuses(
            @ApiParam("Filter given IDs")
            @RequestParam(value = "id", required = false, defaultValue = "") List<String> ids,
            @ApiParam(value = "Sort by property value", allowMultiple = true, format = "propertyName:<asc|desc>", type = "array")
            @RequestParam(value = "_sort", required = false, defaultValue = "") List<Sort> sorts
    )

ids 已按我的预期记录 - 我可以输入多个单独的值：

但是，_sort 始终记录为单个字符串，无论我如何使用 @ApiParam 的不同选项。注册了一个自定义 Spring Converter<String, Sort> bean。

如何强制 Swagger 将 _sort 参数作为字符串列表处理，其中每个项目的格式必须为 "propertyName:<asc|desc>"？

【问题讨论】：

你可以试试@ApiModelProperty(value = "Sort by property value", name="sorts", dataType = "List", format = "propertyName:<asc|desc>", example = "[value1, value2, value3]")

标签： java spring spring-mvc swagger

【解决方案1】：

使用 @ApiImplicitParam 您可以强制 Swagger _sort 参数作为字符串列表

@ApiImplicitParam(name = "_sort", allowMultiple = true, dataType = "string", format = "propertyName:<asc|desc>", paramType = "query",
            value = "Sort by property value")

【讨论】：

非常好！我只是无法使format、collectionFormat 或example 工作 - 我希望它会出现在每个项目的输入框中，但它总是空白。最后我只写了value = "Sort by property value (propertyName:<asc|desc>)"