How to document with Swagger a Spring MVC request param of type List<CustomObject>

Question

Spring Boot 2.1.8, Spring Web 5.1.9, Springfox Swagger 2.8.0, Swagger Annotations/Models 1.5.14

My RestController method signature looks like this:

    @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 is documented as I expect - I can input multiple, separate values:

However, _sort is always documented as a single string, no matter how I play around with different options to the @ApiParam. There is a custom Spring Converter<String, Sort> bean registered.

How can I force Swagger to handle the _sort parameter as a list of strings where each item must have the format of "propertyName:<asc|desc>"?

Answer 1

Using @ApiImplicitParam you can force Swagger _sort parameter as a list of strings

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