quarkus-smallrye-openapi ignores @Parameter (example "...")

[nicolasduminil]

Describe the bug

In a Quarkus 3.7.1 JAX-RS service, I have an endpoint receiving a POST request to create a complex object. I'd like to test it with Swagger, however, using the Try it function, I need to manually fill-in the payload. And since the object is complex, the operation is very fastidious. Hence I'm trying to use the following annotation:

  ...
  Response createCustomer (@Parameter (example = "{\n" +
    "  \"id\": 10,\n" +
    "  \"firstName\": \"John\",\n" +
    "  \"lastName\": \"Doe\",\n" +
    "  \"email\": {\n" +
    "    \"address\": \"john.doe@gmail.com\",\n" +
    "    \"personal\": \"John Doe\",\n" +
    "    \"encodedPersonal\": \"John Doe\",\n" +
    "    \"type\": \"personal\",\n" +
    "    \"simple\": true,\n" +
    "    \"group\": true\n" +
    "  },\n" +
    "  \"addresses\": [\n" +
    "    {\n" +
    "      \"street\": \"75, rue Véronique Coulon\",\n" +
    "      \"city\": \"Coste\",\n" +
    "      \"country\": \"France\"\n" +
    "    },\n" +
    "    {\n" +
    "      \"street\": \"Wulfweg 827\",\n" +
    "      \"city\": \"Bautzen\",\n" +
    "      \"country\": \"Germany\"\n" +
    "    }\n" +
    "  ]\n" +
    "}")
 Customer customer, @Context UriInfo uriInfo) throws IOException {
 ...
}

Expected behavior

I expect that, when testing with the Try it function of Swagger, the payload gets automatically filled-in with the content defined by the annotation.

Actual behavior

The example payload is ignored and the default content is proposed.

How to Reproduce?

I don't have a reproducer.

Output of uname -a or ver

Linux P15s-Gen-2i 5.15.0-97-generic #107-Ubuntu SMP Wed Feb 7 13:26:48 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

Output of java -version

java version "17.0.8" 2023-07-18 LTS Java(TM) SE Runtime Environment (build 17.0.8+9-LTS-211) Java HotSpot(TM) 64-Bit Server VM (build 17.0.8+9-LTS-211, mixed mode, sharing)

Quarkus version or git rev

No response

Build tool (ie. output of mvnw --version or gradlew --version)

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae) Maven home: /usr/share/apache-maven-3.9.6 Java version: 17.0.8, vendor: Oracle Corporation, runtime: /usr/lib/jvm/jdk-17-oracle-x64 Default locale: en_US, platform encoding: UTF-8 OS name: "linux", version: "5.15.0-97-generic", arch: "amd64", family: "unix"

Additional information

N/A

[quarkus-bot[bot]]

/cc @EricWittmann (openapi), @Ladicek (smallrye), @MikeEdgar (openapi), @jmartisk (smallrye), @phillip-kruger (openapi,smallrye), @radcortez (smallrye)

[phillip-kruger]

Can you share your openapi.json or yaml, that gets generated ?

[MikeEdgar]

In addition to what Phillip requested, I suspect you should be using an @RequestBody annotation rather than an @Parameter to represent a POST body.

@RequestBody(content = @Content(example = "your example"))

[nicolasduminil]

@phillip-kruger : I'm attaching here the openapi file. openapi.zip

[nicolasduminil]

@MikeEdgar : using @RequestBody, as you suggested above, instead of @Parameter, didn't change anything to the mentioned behavior.

[phillip-kruger]

@nicolasduminil can you share a small reproducer ?

[nicolasduminil]

@phillip-kruger : I will as soon as I'll have the time. But since you need a reproducer, should I understand that you couldn't reproduce the issue by yourself ? I mean, do you confirm that you could test and using the @Parameter annotation, like in my example, or the @RequestBody one, like mentioned by @MikeEdgar, you succeeded to get the expected result ? And in this case, which one did you use, @Parameter or @RequestBody ?

[MikeEdgar]

I was able to get the example in the output using the @RequestBody annotation. That's the correct annotation for a POST body, although I believe the Swagger annotations use (or did use at one point) the @Parameter annotation. If you try again with @RequestBody maybe share here just the method you test and perhaps there is some other adjustment that you need.

[phillip-kruger]

@nicolasduminil no, it's just easier to look at an issue if there is a reproducer :) @MikeEdgar I'll leave this to you.

[nicolasduminil]

@MikeEdgar : I neglected to mention that, in my case, I have separated the interface and implementation, as follows:

public interface CustomerResource
{
  @POST
  @Operation(description = "Create a new customer")
  @APIResponse(responseCode = "500", description = "An internal server error has occurred",    content = @Content(mediaType = APPLICATION_XML))
  @APIResponseSchema(value = Customer.class, responseDescription = "The new customer has been created", responseCode = "201")
  ...
  Response createCustomer (Customer customer, @Context UriInfo uriInfo) throws IOException;
}
...
@Path("customers")
@Produces(APPLICATION_JSON)
@Consumes(APPLICATION_JSON)
public class CustomerResourceImpl implements CustomerResource
{

  @Override
  public Response createCustomer(Customer customer, @Context UriInfo uriInfo) throws IOException
  {
    ...
  }
...
}

Does it change anything ? Is that supposed to work as well or is there any obligation to annotate the implementation and not the interface ?

[nicolasduminil]

@phillip-kruger : LOL ! It's even easier not to look at all ...

[MikeEdgar]

I neglected to mention that, in my case, I have separated the interface and implementation Does it change anything ? Is that supposed to work as well or is there any obligation to annotate the implementation and not the interface ?

It should support annotations like you have them. In your code snippet I don't see the @RequestBody, in which location are you using it?

[nicolasduminil]

Old and unfollowed issue, closing.