TCK error - OASConfigExcludeClassesTest$testExcludedClasses requires incorrect OpenAPI document to pass

TL;DR

To pass this TCK test (and perhaps others), the server must generate an OpenAPI document that conflicts with the conventional behavior as described in the JAX-RS spec and as implemented by at least some MicroProfile-compliant servers.

Specifically, the test requires that the OpenAPI document declare endpoints that the server does not, in fact, expose. This is a problem in that the TCK requires servers to produce incorrect OpenAPI documents.

Details

In the TCK test in the issue title, JAXRSApp$getSingletons returns four JAX-RS resource class instances:

• AirlinesResource
• AvailabilityResource
• BookingResource
• ReviewResource

The class does not override getClasses so the superclass implementation returns the empty set.

The JAX-RS spec https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html#servlet describes how servlet implementations must handle this:

if both Application.getClasses and Application.getSingletons return an empty collection then all root resource classes and providers packaged in the web application MUST be included

It continues (importantly):

If either getClasses or getSingletons returns a non-empty collection then only those classes or singletons returned MUST be included in the published JAX-RS application.

Of course, MicroProfile neither refers to nor implements servlets, but it is very reasonable for our users to expect MP-compliant servers to honor the JAX-RS semantics described there. Two server implementations I checked (OpenLiberty and Helidon) do so and I suspect so do others.

In contrast, the subject TCK test as written requires 10 path elements in the returned OpenAPI document. Two of the resources returned from JAXRSApp$getSingletons–ReviewResource and AvailabilityResource–are excluded by the mp.openapi.scan.exclude.classes config setting used in the test. For the document to contain 10 path elements it must include the endpoints not only from AirlinesResource and BookingResource but also those from UserResource which is not represented in the return values from JAXRSApp$getResources or getSingletons. Including the UserResource endpoints would be expected if JAXRSApp overrode neither getClasses nor getSingletons but it does override getSingletons.

This test seems flawed in that:

1. It requires the server to produce an OpenAPI document which conflicts with the behavior described in the JAX-RS spec.
2. For servers which follow the semantics as described in the JAX-RS spec, to pass the TCK they must, in some cases, produce OpenAPI documents which conflict with the endpoints they actually expose.

There might be other tests with similar behavior.

[Emily-Jiang]

@MikeEdgar I am afraid it is too late. It can be done after the release. We can do a service release straightaway after MP 5.0. Please don’t push the changes until the final release is staged.

[Azquelt]

There are other tests which explicitly look for /user paths (e.g. AirlinesAppTest.testOperationUserResource), so I’ve opened #510 to add the UserResource class to the set of singletons.