OpenAPI Generator Pageable with Spring

Question

I would like the OpenAPI Generator (https://github.com/OpenAPITools/openapi-generator) to be able to generate Pageable parameter in API according to the implementation in Spring Boot Data. I've been trying to find a suitable, out of the box solution, but couldn't find one.

Ideally, this Pageable parameter should be added only to GET methods in a following manner:

default ResponseEntity<User> getUser(@ApiParam(value = "value",required=true) @PathVariable("id") Long id, **Pageable pageable**)

So after implementing this interface in my Controller I would need to override it and having this aforementioned Pageable parameter. I don't want to have separate parameters for size or page, only this Pageable here.

Thanks for any tips and help!

Answer 1

Unfortunately this is no final solution but it is half way. Maybe it is of help anyway.

By defining the pageable parameters (size, page etc.) as an object query parameter it is possible to tell the generator to use the Spring object instead of generating a Pageable class from the api. This is done by an import mapping.

in gradle:

openApiGenerate {
    ....
    importMappings = [
        'Pageable': 'org.springframework.data.domain.Pageable'
    ]
}

which tells the generator to use the Spring class instead of the one defined in the api:

openapi: 3.0.2
info:
  title: Spring Page/Pageable API
  version: 1.0.0

paths:
  /page:
    get:
      parameters:
        - in: query 
          name: pageable
          required: false
          schema:
            $ref: '#/components/schemas/Pageable'
      responses:
        ...

components:
  schemas:
    Pageable: 
      description: minimal Pageable query parameters
      type: object
      properties:
        page:
          type: integer
        size:
          type: integer

The issue with the mapping is that the generator still adds a @RequestParam() annotation and that breaks it again. It only works if it is NOT annotated.

If you are a bit adventurous you could try openapi-processor-spring (i'm the author). It it does handle the example above. But it may have other limitations you don't like.