Add smallrye-openapi's @APIResponse on built-in ExceptionMappers

[cvgaviao]

Quarkus with smallrye-openapi can scan for @Provider ExceptionMappers and add them to endpoints that throw that exception.

(quarkusio/quarkus#44035)

@Provider
public class BundleRenderValidationExceptionMapper implements ExceptionMapper<BundleRenderValidationException> {
    @Override
    @APIResponse(
            responseCode = "400",
            description = "Validation of bundle failed",
            content = @Content(mediaType = "application/problem+json", schema = @Schema(implementation = HttpProblem.class))
    )
    public Response toResponse(BundleRenderValidationException exception) {
        return exception.getResponse();
    }
}

Describe the solution you'd like

Would be nice to have those @APIResponse on the built-in ExceptionMappers provided by this extension, so they can be scanned, and the associated HTTP Errors to appear on the generated swagger-ui page

[lwitkowski]

@cvgaviao that sounds like a useful feature, we would only have to figure out how to implement this properly with openapi extension being optional (so that this extension can work both with and without this feature by detecting the existence of openapi, preferably in build time). Annotation will probably not be usable because of that, but programmatic interaction with openapi extension api may work.
I personally may not have time in the near future to look into it though.

[acoburn]

If this module depends on only the microprofile APIs (via the quarkus-bom):

<dependency>
  <groupId>org.eclipse.microprofile.openapi</groupId>
  <artifactId>microprofile-openapi-api</artifactId>
</dependency>

then, with the suggested annotations above, if a consumer of this module doesn't use the quarkus-smallrye-openapi implementation, the annotations will simply be ignored. But everyone who does make use of that quarkus extension will see these annotations appear in the generated OpenAPI YAML.

[lwitkowski]

If this module depends on only the microprofile APIs (via the quarkus-bom):

<dependency>
  <groupId>org.eclipse.microprofile.openapi</groupId>
  <artifactId>microprofile-openapi-api</artifactId>
</dependency>

then, with the suggested annotations above, if a consumer of this module doesn't use the quarkus-smallrye-openapi implementation, the annotations will simply be ignored. But everyone who does make use of that quarkus extension will see these annotations appear in the generated OpenAPI YAML.

That would work indeed, but it would add 100kB transitive dependency with tens of classes potentially polluting everybody's classpath even if it's not used. That's why I'm hesitant to do it this way, and would prefer optional dependency (just like with zalando's problem lib, or quarkus-smallrye-metrics:
https://github.com/quarkiverse/quarkus-resteasy-problem/blob/main/runtime/pom.xml

[turing85]

There's also the option to add the response type programmatically (see https://github.com/turing85/quarkus-jackson-json-patch/blob/4aa61d789aebd1a54d6a205b20e8a4d365e554cc/src/main/java/de/turing85/quarkus/json/patch/openapi/JsonPatchOpenApiFilter.java for an example). Not sure if automatic mapping then still works, but this would allow the possibility to add a bean at compile-time when microprofile is present and maybe an additional feature flag is present. This should make it possible to mark the necessary dependencies as optional.