APIResponse and APIResponses should target TYPE as well

[jvs64893]

Currently APIResponse and APIResponses use:
@Target({ ElementType.METHOD })

The Swagger equivalent handles this differently (see
https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/responses/ApiResponses.java):
@Target({METHOD, TYPE, ANNOTATION_TYPE})

This makes it possible to add a response to all @Operations in a class. It would be great if this was possible with MP OpenAPI as well!

[EricWittmann]

Can you provide some pseudo/sample code that shows the use-case you're asking for. I believe this is about annotating an entire JAX-RS class with e.g. @APIResponse so that the response is applied to all operations defined in the class. I presume that would be useful for a number of error response conditions - in particular 500. So you don't have to repeatedly tag every method with a "Server Error" api response when of course every method could possibly throw that. Am I correct in my understanding of what this issue is referring to?

[jvs64893]

@EricWittmann
You're correct, that is exactly the use case.

Sample code would be something like that:

@APIResponses(value = {@APIResponse(responseCode = "500",
        content = @Content(
            schema = @Schema(implementation = Error.class)),
        description = "Error")})
public class Test {

  @APIResponses(value = {
      @APIResponse(responseCode = "200",
          content = @Content(schema = @Schema(
              implementation = Test.class)),
          description = "Operation executed successfully"),
      @APIResponse(responseCode = "400", content = @Content(
          schema = @Schema(implementation = Error.class)),
          description = "Error")})
  @Operation(summary = "Testmethod", description = "Test")
  @GET
  public Response test() {
  ...
  }

}

The generated documentation would add the 500 error to all methods, plus the specific APIResponses that the methods have (200 + 400 in this case).

[EricWittmann]

OK great thanks. I've marked this as a hangout topic for us to discuss on our next specification call.

[phillip-kruger]

+1

[EricWittmann]

+1

[EricWittmann]

@MikeEdgar and @arthurdm - this issue gets two resounding +1's from us. I think we should go ahead and tag this as "help wanted" or whatever the next step is to getting this done. Unless either of you has any reservations...

[MikeEdgar]

+1 from me as well. This is a nice feature.

[arthurdm]

+1

[jmini]

@jvs64893 will you propose a PR for that?

The annotation should be changed and I think it would be great to have a TCK case for this.

[renzodf]

Hello,

It would be great to also add the ANNOTATION_TYPE in Target like Swagger does. The main usecase I see is the definition of custom meta annotation like this one:

@ApiResponse(code="404", message="Resource not found")
public @interface MyResourceNotFound

allowing to save a lot of repetitive code.

The example is extracted from this Swagger topic: swagger-api/swagger-core#690

[szymonblaszczyk]

Both the original proposal and the extra suggestion by @renzodf would be a great addition to this lib's capacity to reduce the boilerplate written and time taken to document uniform and/or repetitive APIs.

Has any further action taken place in this direction? Is any assistance needed?

[MikeEdgar]

Hi @szymonblaszczyk - if you have some bandwidth, I certainly think a PR with the suggested annotation changes and TCK test (tests?) to verify the changes to behaviour would be welcome!

I am also curious about feedback from others as well regarding the use of ANNOTATION_TYPE in the annotation's Target. I don't think it's a bad idea, but it might be best to consider something like that generally across all (or several) of the annotations.

CC: @EricWittmann, @jmini, @phillip-kruger