Allow Global APIResponse Status Reuse

[MikeEdgar]

When used inside of @Components, the responseCode value of an @APIResponse is not usable from the operations where it is referenced. Using multiple @APIResponse annotations on a method with a ref to a global response results in a single default response.

Example:

    @OpenAPIDefinition(
            info = @Info(title = "Cool API", version = "0.1"),
            components = @Components(responses = { 
                @APIResponse(responseCode = "404", description = "Not Found!", name = "NotFound"),
                @APIResponse(responseCode = "500", description = "Server Error!", name = "ServerError")    
            }))
    static class CoolAPIApp extends Application {
    }

    @Path("pets")
    static class PetResource {
        @Path("{id}")
        @GET
        @Consumes(MediaType.APPLICATION_JSON)
        @Produces(MediaType.APPLICATION_JSON)
        @APIResponse(responseCode = "200")
        @APIResponse(ref = "NotFound")
        @APIResponse(ref = "ServerError")
        public Object getPet(@PathParam("id") String id) {
            return null;
        }
    }

The resulting OpenAPI shows that the 404 status is "lost".

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "Test title",
    "version" : "0.1"
  },
  "paths" : {
    "/pets/{id}" : {
      "get" : {
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "default" : {
            "$ref" : "#/components/responses/ServerError"
          },
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "responses" : {
      "NotFound" : {
        "description" : "Not Found!"
      },
      "ServerError" : {
        "description" : "Server Error!"
      }
    }
  }
}

My expectation as a user is that the response status from the global component should be known to the scanner and used as the key to the operation's responses map (via an implementation-specific field in APIResponseImpl). Specifying both responseCode and ref on the operation's annotation is possible, but results are undefined for other properties when ref is given, and it also results in repeated information.

@EricWittmann , @phillip-kruger - w.d.y.t.? I've already coded this, but wanted to hold off on a PR in case some additional discussion is needed or a different approach is possible that I'm not thinking of.

[phillip-kruger]

I agree ! Anything in the spec about this ?

[MikeEdgar]

Nothing in the spec that I could identify...

[phillip-kruger]

Cool. Maybe we should bring it up there as well. Would be good to clarify there

[MikeEdgar]

I agree - I'll open up an issue over there later today. If we are good with implementing something here first, I'll go ahead and open the PRs for master and 2.0.x later today also.

[phillip-kruger]

Cool !! Thanks !