How to tell openapi generator to use the method return type when using @APIResponse?

[matevskial]

Suppose I have a resource like:

@GET
@Path("/someendpoint"
@APIResponse(responseCode = "200", responseDescription = "OK - data fetched")
public Uni<RestResponse<GenericDataResponse<SomeDto>>> someEndpoint() {
}

With above code, the generated openapi schema loses information about the return type. If I use @Content and @Schema as follows

@GET
@Path("/someendpoint"
@APIResponse(responseCode = "200", responseDescription = "OK - data fetched", @Content(mediaType = MediaType.APPLICATION_JSON, schema = @Schema(implementation = GenericDataResponse.class))))
public Uni<RestResponse<GenericDataResponse<SomeDto>>> someEndpoint() {
}

then I lose the information about SomeDto in the openapi schema.

IS there similar option like https://docs.swagger.io/swagger-core/v2.2.3/apidocs/io/swagger/v3/oas/annotations/responses/ApiResponse.html#useReturnTypeSchema--

useReturnTypeSchema

public abstract boolean useReturnTypeSchema

Set to true to resolve the response schema from method return type

[quarkus-bot[bot]]

/cc @EricWittmann (openapi), @MikeEdgar (openapi), @phillip-kruger (openapi)

[MikeEdgar]

Do you get the expected response schema if @APIResponse is completely removed?

[matevskial]

Sure, here's how GenericDataResponse looks:

@Value
@SuperBuilder
@EqualsAndHashCode(callSuper = true)
public class GenericDataResponse<D> extends BaseResponse {

    D data;

    public static <D> GenericDataResponse<D> withData(D data) {
        return GenericDataResponse.<D>builder().data(data).build();
    }

    public static <D> GenericDataResponse<D> failure(ErrorCode errorCode) {
        return GenericDataResponse.<D>builder().errorCode(errorCode).build();
    }

    public static <D> GenericDataResponse<D> failure(String error) {
        return GenericDataResponse.<D>builder().error(error).build();
    }

    public static <D> GenericDataResponse<D> failure(ErrorCode errorCode, List<String> errors) {
        return GenericDataResponse.<D>builder().errorCode(errorCode).errors(errors).build();
    }
}

Here's BaseResponse:

@EqualsAndHashCode
@Getter
@SuperBuilder
public abstract class BaseResponse {

    @Singular
    private final List<String> errors;

    private final ErrorCode errorCode;

    public boolean isSuccess() {
        return (errors == null || errors.isEmpty()) && errorCode == null;
    }
}

[MikeEdgar]

Given those classes and a Bean class I made up, I'm getting something like this. Are any of the classes involved in a jar file separate from the main application?

{
  "openapi" : "3.1.0",
  "components" : {
    "schemas" : {
      "Bean" : {
        "type" : "object",
        "properties" : {
          "f1" : {
            "type" : "string"
          },
          "f2" : {
            "type" : "integer",
            "format" : "int32"
          }
        }
      },
      "ErrorCode" : {
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "string"
          }
        }
      },
      "GenericDataResponse" : {
        "type" : "object",
        "properties" : {
          "errors" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          },
          "errorCode" : {
            "$ref" : "#/components/schemas/ErrorCode"
          },
          "success" : {
            "type" : "boolean"
          },
          "data" : {
            "$ref" : "#/components/schemas/Bean"
          }
        }
      }
    }
  },
  "paths" : {
    "/api/someendpoint" : {
      "get" : {
        "responses" : {
          "200" : {
            "description" : "OK - data fetched",
            "content" : {
              "*/*" : {
                "schema" : {
                  "$ref" : "#/components/schemas/GenericDataResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}

[matevskial]

Every class if from the same jar file. Can you paste the controller code to see the openapi annotations you are using?

[MikeEdgar]

It's basically your original endpoint. However, I am running it from a unit test in the scanner library smallrye-open-api. If there's a difference it seems as though it's part of the larger environment of your app. Could you post small app that demonstrates the issue? I can dig through that and try to pinpoint the cause.

@jakarta.ws.rs.Path("api")
class Api {
    @jakarta.ws.rs.GET
    @jakarta.ws.rs.Path("/someendpoint")
    @APIResponse(responseCode = "200", description = "OK - data fetched")
    public Uni<RestResponse<GenericDataResponse<Bean>>> someEndpoint() {
        return null;
    }
}

[matevskial]

Now this is interesting: I've been unable to reproduce the issue. You are correct, what I reported as an issue should already be NOT an issue. But I am sure I've experienced the issue I described since I remember searching the internet if Smallrye openapi supports something like useReturnTypeSchema, so I am not sure what caused the issue. At the same time I also remember having an (unrelated to this) issue with the option mp.openapi.scan.exclude.packages where it simply didn't work and I had to add @Operation(hidden = true) to every controller method in a rest resource class, but that's for another discussion. I'll test again and see if mp.openapi.scan.exclude.packages works.

Update: mp.openapi.scan.exclude.packages=com.asdf.efg worked while mp.openapi.scan.exclude.packages=com.asdf.efg.* did not work.