Invalid assertion in AirlinesAppTest::testCallbackOperationAnnotations

Here is the assertion I think is problematic:

vr.body(endpoint + ".get.responses.'200'.content.'application/json'.schema.ref", equalTo("#/components/schemas/Review"));

The above assertion appears to be verifying this part of the airlines test app:

@Content(mediaType = "application/json",
                  schema = @Schema(
                            type = SchemaType.ARRAY,
                            implementation = Review.class
                  )
         )
)

However, I question the idea that the above annotation should result in an OAI schema with a $ref. It seems to me that the only time you should get a $ref is if you actually reference something in the annotation. Otherwise the schema should be inline.

The TCK test seems to be asserting (typo of Review/Booking aside) that the resulting OAI schema should be:

{
    "type" : "array",
    "$ref": "#/components/schemas/Review"
}

Even if the implementation property of the @Schema annotation should result in a $ref, the result should be something like this:

{
   "type" : "array",
   "items": {
      "type": "object",
      "$ref": "#/components/schemas/Review"
   }
}

I think we need to have a discussion about @Schema and its implementation property vs its ref property. I think an OAI $ref should only occur when using the ref property of the annotation.

[EricWittmann]

Yes, let’s discuss next hangout for sure. I can be convinced certainly, but it might be more complicated than you expect.

Here is one thing to consider (from the spec) when we have that hangout:

The @Schema annotation has a complex set of possible combinations. It can placed on POJOs (and their fields / methods) and referenced from many other annotations. In the event that a @Schema#implementation value points to a POJO that also contains a @Schema annotation, the values are merged but with precedence given to the referrer annotation (i.e. the one that contains the implementation key). This allows POJO models to be reusable and configurable.

[arthurdm]

Fixed by PR #199