OpenAPI and API operations response with schema

[sombraglez]

I have found an unexpected behavior using OpenAPI in combination with API operations which include a schema definition:

By the following POST operations, the resulting OpenAPI do not contain any schema into the generated post responses:

@POST
@APIResponseSchema(value = Fruit.class, responseCode = "200", responseDescription = "Success")
public Response addWithResponseSchema(Fruit fruit) {
        var location = URI.create("/fruits/" + fruit.name);
        return Response.created(location).build();
}

the corresponding generated OpenAPI definition does not include the defined response schema:

post:
      tags:
      - Fruit Resource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        "200":
          description: Success
          content: {}

or with:

@POST
@APIResponse(content = @Content(schema = @Schema(implementation = Fruit.class)), responseCode = "200", description = "Success")
public Response addWithResponseContent(Fruit fruit) {
        var location = URI.create("/fruits/" + fruit.name);
        return Response.created(location).build();
}

the generated response into the OpenAPI definition looks similar (without schema into the response):

post:
      tags:
      - Fruit Resource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        "200":
          description: Success
          content: {}

But by adding a content type into the API operation definition (using for example @Produces(MediaType.APPLICATION_JSON)), the generated response contains the configured schema. For example:

post:
      tags:
      - Fruit Resource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fruit'

As I understand, the annotation @Produces(MediaType.APPLICATION_JSON) was not longer explicitly expected in the API operations definition.

But in the case of an REST End-Point returning a generic Response and combined with a schema definition , what I understand for the generated OpenAPI above, we are forced to use the annotation @Produces(MediaType.APPLICATION_JSON)

Summing up: is this behavior from your point of view expected or there is an issue related to my use case?

[quarkus-bot[bot]]

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