«Чиним» 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.