JAX-RS Reader Omits Valid Endpoint Definitions Due to "Skip if Path is Same as Parent" Logic #3011
Description
Background
The JAX-RS Reader intentionally skips methods which have a relative path that is equivalent to its "parent".
This behavior appears to be intended to omit non-endpoint methods, such as those within an "@ApplicationPath annotated application extending resource config".
Problem Statement
This JAX-RS Reader behavior has the unintended consequence that it omits valid endpoint methods in a root resource class annotated with @Path("/") when an endpoint in that resource is defined without a @Path annotation.
Use Case
One use case for this path configuration is a single application containing multiple JAX-RS implementations.
If it is desired that these APIs share a common "base" path segment (e.g. /example), then a single root resource may not require an additional path segment.
In this configuration, you may have one API annotated with @ApplicationPath("/example/one") and another with @ApplicationPath("/example/two").
Either or both APIs may have a single root resource class which would then be annotated with @Path("/") and include an endpoint method without a @Path annotation.
Example
The following resource configuration classes for two APIs with shared "base" path segment
@ApplicationPath("/example/one")
public class ExampleOne extends ResourceConfig {
...
}
@ApplicationPath("/example/two")
public class ExampleTwo extends ResourceConfig {
...
}
and a root resource class including endpoint without @Path annotation in the package associated with the ExampleOne API
@Path("/")
public class ExampleOneResource {
@GET
public Response read() { return Response.noContent().build(); }
}
generate the following specification - note the missing GET /example/one endpoint definition
{
"openapi" : "3.0.1",
"info" : {
"title" : "Example API",
"version" : "1.0.0"
}
}
Details
This issue is caused by the java.io.swagger.v3.jaxrs2.Reader class' primary 'read' method, lines 394-398 below.
// skip if path is the same as parent, e.g. for @ApplicationPath annotated application
// extending resource config.
if (ignoreOperationPath(operationPath, parentPath) && !isSubresource) {
continue;
}
When this method is called during the processing of the ExampleOneResource class in the example above,
this logic omits the GET endpoint method due to its path being the same as the @ApplicationPath annotation on the ExampleOne class.
Proposed Solution
This check should inspect for the existence of one of the JAX-RS [HTTP] resource method designator annotations (e.g. javax.ws.rs.GET) to determine whether or not to ignore a potential endpoint method instead of making the decision based on the path.
To my knowledge, these are mandatory on any JAX-RS endpoint method declaration.