«Чиним» OpenApi в springdoc-open-api

На смену springfox пришел springdoc. Он приносит нам в проект Swagger и поддерживает спецификацию OpenApi 3. Но есть еще некоторые шерховатости, а именно правильное отображение параметров запроса для сортировки и постраничного вывода.

Давайте посмотрим, можно ли их исправить и как это сделать.

Проблема

После добавления в проект артефакта springdoc-openapi-ui становится доступна страница http://localhost:8080/swagger-ui.html
Все красиво и аккуратно кроме параметров типа Pageable и Sort.

    @GetMapping("/sort")
    public @ResponseBody void sort(Sort sort) {
        //
    }
    
    @GetMapping("/pageable")
    public @ResponseBody void pageable(Pageable pageable) {
        //
    }

Описание Pageable только выглядит странно, но пользоваться им можно.

Объект:

{
  "page": 0,
  "size": 1,
  "sort": [
    "string"
  ]
}

будет преобразован в набор параметров строки запроса:

curl -X 'GET' 
'http://localhost:8080/pageable?page=0&size=1&sort=string' 
-H 'accept: /'

А вот описание для Sort не соответствует действительности. Нам нужен параметр строки запроса sort, а не вот это:

К тому же в этих объектах параметрах нет описаний.

Устранение

Для Pageable все просто. Достаточно перед параметром метода аннотацию @ParameterObject

    @GetMapping("/pageable")
    public @ResponseBody void pageable(@ParameterObject Pageable pageable) {
        //
    }

Красивое...

Для Sort так сделать не получится. Но выход есть:

1. Скрываем настоящий параметр с помощью аннотации @Parameter(hidden = true);

2. Описываем правильный параметр самостоятельно.

Получается следующая конструкция:

    @Parameter(in = ParameterIn.QUERY, 
        description = "Sorting criteria in the format: property(,asc|desc). " +
                "Default sort order is ascending. " +
                "Multiple sort criteria are supported.",
        name = "sort",
        required = false,
        array = @ArraySchema(schema = @Schema(type = "string")))
    @GetMapping("/sort")
    public @ResponseBody void sort(@Parameter(hidden = true) Sort sort) {
        //
}

Теперь все выглядит так, как и задумывалось. Swagger можно использовать, а спецификацию OpenApi отдавать FrontEnd-разработчикам.

Надеюсь, что в скором времени для Sort тоже можно будет использовать аннотацию @ParameterObject.