REST Data with Panache paging parameters should be visible at Swagger/OpenAPI

[alievrenkut]

Description
I created a PanacheEntityResource and generated OpenAPI description but pagination parameters are not visible to Swagger so I can not give pagination parameter from Swagger UI. I also generated Typescript API from it using swagger-typescript-api. I can not see paging parameters from Typescript side too.

Could you add necessary info at RestDataResource?

[quarkusbot]

/cc @EricWittmann, @MikeEdgar, @phillip-kruger
/cc @FroMage, @loicmathieu

[phillip-kruger]

Hi @alievrenkut . Thanks for this issue. Do you perhaps have a small project I can look at ?

[alievrenkut]

Hi you can clone: https://github.com/alievrenkut/quarkus-rest-data-panache which is sample project I created with quarkus.

You can see that after I run "gradlew quarkusDev" you will see that there is no page parameters:

[phillip-kruger]

Hi @alievrenkut - Thanks for this. This is a feature request to the quarkus-rest-data-panache extension.
The normal JAX-RS code generated by this extension does not contain any OpenAPI annotations. And because the pagination used query parameters, it's not automatically generated with OpenAPI. (It does not generate code with @QueryParam, but rather get the info of the UriInfo)

I would say the panache maintainers needs to look at how to do this best. I would suggest :

1. Check if OpenAPI extension is included
2. If so, and paging is active on a list method, add something like this in the generated code:

@Parameter(name = "page", description = "The page number", in = ParameterIn.QUERY, schema = @Schema(implementation = Integer.class))
@Parameter(name = "size", description = "The number of items per page", in = ParameterIn.QUERY, schema = @Schema(implementation = Integer.class)

@FroMage - w.d.y.t ? I am happy to do the PR if you agree with the approach. Let me know.

[FroMage]

I would have to remember why @gytis didn't use @QueryParam first.

[gytis]

Because the pagination can be disabled, I have decided to use UriInfo instead of having unused method parameters in an interface. However, if it is causing more issues that solving, maybe it is worth reconsidering the approach?

[phillip-kruger]

I think we can still use UriInfo, just also add the OpenAPI annotations when pagination is possible. (And OpenAPI extension is added)

[FroMage]

Isn't it simpler to add query parameters (since they're always optional) rather than include an optional dependency on OpenAPI?

[phillip-kruger]

Yes definitely !

[gytis]

I'm ok with adding the query params in place of the UriInfo. The only issue is that the method definition will get longer and the user will have to copy it all if he'll want to customise it. For example:

public interface MyEntityController extends PanacheEntityResource<MyEntity, Long> {
    @MethodProperties(path = "/some-custom-path")
    Response list(int page, int pageSize, String sort);
}

[FroMage]

I think that's fine, most IDEs can do that if you add the @Override and it will be checked too.

[gytis]

OK, assign this issue to me then and I'll sort it out.

[FroMage]

Your wish is my command.