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!

Stonwin

As far as I know that is not possible without adding size/page to the api. Why do you want to hide it? Without it nobody knows it is paging... – Grube

@MartinHauner We would like to have page,size,sort in our openAPI .yaml file, so our other teams know that the paging is there, but in our generated API as a backend, we would like to have only this Pageable param, since spring will handle that having page,size,sort param and transform it into Pageable object – Stonwin

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.

Grube

thanks! I wish it was more configurable than it seems to be, great idea with creating your processor, I still need to check this out :) – Stonwin

What do you mean by 'works if it is not annotated'? Annotations as I understand are also added by openapi generator plugin. – Bemused

at time of writing, (I don't know if it still the case) the generator added the @RequestParam() annotation to the pageable parameter of the controller method. This confused Spring and the automatic binding of the page& size parameters to the Pagable object did not work. It did work only if the Pagable parameter was not annotated with @RequestParam. – Grube

Kotlin-Spring v5.3.1 generates a "pageable: Pageable?" parameter without @RequestParam annotation. – Fulvi

im playing with the last openapi generator and gradle plugin 6.2.1 and it does not generate @RequestParam. parameter binding to query string is working. The only problem that generator generates useless data class anyway, despite it is overrided by Spring class, and I need to delete it. – Niccolo

Answer 2

I have another solution, using 'openapi-generator' u can give a vendorextension flag in the spec file 'x-spring-paginated'

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

paths:
  /page:
    get:
      x-spring-paginated: true
      responses:
        ...

You might experience an issue with spring-doc where you either can add the missig dependency or change the documentation-provider under the configOptions to source.

I.G. for the maven plugin

...
<configuration>
  ...
  <configOptions>
   <documentationProvider>source</documentationProvider>
   ...
  </configOptions>
</configuration>

Lemures