Quarkus OpenAPI Generated documentation for @BeanParam does not reflect @Parameter if you are using a setter

[sean-scott-lr]

Describe the bug
Quarkus OpenAPI Generated documentation for @BeanParam does not reflect the information coded in an @Parameter annotation if you are using a setter.

It appears that you must annotate a member variable instead of a setter method with Both @QueryParam and @Parameter in order for the API Doc to work properly. However, in our case, we are setting the value into a delegate and this workaround will not work for us.

Expected behavior
The API doc that is produced, contains the information that exists in the annotations.

Actual behavior
The @QueryParam shows up in the documentation, with no additional information.

To Reproduce
Steps to reproduce the behavior:

1. Create a class to use as your BeanParam.
2. Add a field as a private member and create a getter and setter for it.
3. Annotate the setter with @QueryParam and @Parameter ( description , required = true, examples, etc )
4. View the generated API doc. Note that none of the parameter information is reflected. The biggest issue being that the field does not reflect that it is required.

Configuration

# Add your application.properties here, if applicable.

Screenshots
(If applicable, add screenshots to help explain your problem.)

Environment (please complete the following information):

Environment (please complete the following information):

• Output of uname -a or ver:
  Darwin XXXXX 19.4.0 Darwin Kernel Version 19.4.0: Wed Mar 4 22:28:40 PST 2020; root:xnu-6153.101.6~15/RELEASE_X86_64 x86_64

• Output of java -version:
  openjdk version "11.0.6" 2020-01-14
  OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.6+10)
  OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.6+10, mixed mode)

• GraalVM version (if different from Java):

• Quarkus version or git rev:
  1.3.1.Final

• Build tool (ie. output of mvnw --version or gradlew --version):
  Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)

Additional context
(Add any other context about the problem here.)

[quarkusbot]

/cc @EricWittmann

[MikeEdgar]

@sean-scott-lr , do you have the name and in properties specified in the @Parameter annotation?

[sean-scott-lr]

Here is an example of what we have:

  @DefaultValue("10") // JAX-RS
  @QueryParam(LIMIT_QP_NAME) // JAX-RS
  @Parameter(description = "The maximum number of results that a response page can contain.") // OAS
  public void setLimit(int limit) {
    

[r00ta]

@sean-scott-lr What about

  public void setLimit(
    @DefaultValue("10") // JAX-RS
    @QueryParam(LIMIT_QP_NAME) // JAX-RS
    @Parameter(description = "The maximum number of results that a response page can contain.") 
    int limit) {
...
```?

[MikeEdgar]

@sean-scott-lr , please try:

@Parameter(name = LIMIT_QP_NAME, in = ParameterIn.QUERY, description = "The maximum number of results that a response page can contain.")

[sean-scott-lr]

@MikeEdgar Yes that does work. Was I misusing the API?

[sean-scott-lr]

@r00ta That works too. Are there docs somewhere I missed that show the usage scenarios?

[MikeEdgar]

@r00ta's solution will also work. The name and in are required properties (per the JavaDocs), but in some cases the annotation scanner attempts to be more lenient by allowing them to be omitted. An annotated method is one of the situations where at least the name must be given. I'll need to look into why methods require at least the name. I do not remember and I did not add a comment at the time :-)

[sean-scott-lr]

@MikeEdgar @r00ta Thank you

[sean-scott-lr]

@r00ta Note, that in your solution with the @QueryParam in the setter works for both documentation and functionality. However, with @PathParam my code is no longer functional. ( the parameter is not set ).

[phillip-kruger]

Can we close this one ? @MikeEdgar ? @sean-scott-lr ?

[MikeEdgar]

@phillip-kruger - this was likely fixed with smallrye/smallrye-open-api#333 or smallrye/smallrye-open-api#293.