Spring REST Pageable / Query Parameters in Swagger

Question

I'm trying to implement paging in my REST service.

TAKE 1:

public Page<Item> getPagedItems(Pageable pageable)

This is a known bug in SpringFox / Swagger where the Swagger page shows the wrong parameter names. Plus, I just want page & size options.

TAKE 2:

public Page<Item> getPagedItems(@RequestParam(name="page", required=true) int page, @RequestParam(name="page", required=true) int size)

This gives me the correct params, but it doesn't let me set the param descriptions or example values.

TAKE 3:

@ApiImplicitParams({
    @ApiImplicitParam(name="page", value="page description", required=true, example="0", dataType="int"),
    @ApiImplicitParam(name="size", value="size description", required=true, example="10", dataType="int")
})
public Page<Item> getPagedItems(int page, int size)

This has yet ANOTHER bug where example="0" doesn't work, but every other value except that one works lol. If I change the datatype to String then it'll display the 0 example value, but then it'll let you put in anything in the text box. Also tried "0 ", "0.0", "0\0", etc. Stuff like that.

If I don't set examples, then Springfox throws an exception complaining about no examples lol. The closest thing I can do is put 0 for both with both blank. Ugh. Having 0 / 10 isn't a good option since the 0 doesn't work, but the 10 does.

Any idea how to get an example of 0 to work? Spring Fox doesn't seem to be too well supported, even for open source, so no response on GitHub.

Or some other way of having an example AND description?

Answer 1

We created a inherited annotation and used that:

 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@ApiImplicitParams({
    @ApiImplicitParam(name = "page",  dataTypeClass = int.class,defaultValue = "0", example = "0", paramType = "query", value = "Results page you want to retrieve (0..N)"),
    @ApiImplicitParam(name = "size", dataTypeClass = int.class ,example = "10", paramType = "query", value = "Number of records per page."),
    @ApiImplicitParam(name = "sort", allowMultiple = true, dataTypeClass=String.class, paramType = "query", value = "Sorting criteria in the format: property(,asc|desc). "
            + "Default sort order is ascending. " + "Multiple sort criteria are supported.")  
})
public @interface ApiPagingParams {

}

usage

@ApiPagingParams
@ResponseStatus(HttpStatus.OK)
@GetMapping("/entity") 
ResponseEntity<Page<...>> getSurveyEntityList(@ApiIgnore("see @ApiPagingParams") @PageableDefault(page = 0, size = 10) Pageable pageable,...)