-
Notifications
You must be signed in to change notification settings - Fork 82
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add an annotation to declare what JAX-RS resources are associated with a given Application
#520
Comments
Any progress with this issue? We are currently unable to use mp openapi since our deployed WAR contains multiple jax-rs applications. The generated docs are faulty, only one, seemingly arbitrarily choosen, application path is prepended to all paths. |
Maybe it would also be a good idea to also allow this to be set via configuration? On the call this week we thought of:
Or possibly:
I'm not really a fan of having to do this - it would be preferable for the implementation to get the list of applications and their root resources from JAX-RS if possible - but if we want to allow implementations to pre-compute this, or to build an OpenAPI document at build time, then I think we do need some way of specifying this information. |
Developers can extend the JAX-RS
Application
class, for example to specify an app path for all resources within that app.Such subclasses can also override
getClasses
andgetSingletons
.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:
It continues (importantly):
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.
There is no way for the developer to declare, at build-time, this same information using annotations so that the OpenAPI document derived from annotations agrees with the runtime behavior of the application. It would be possible for MP OpenAPI implementations to instantiate the
Application
s and invoke theirgetClasses
andgetSingletons
methods simply to derive the correct OpenAPI document, but this could force such instantiation earlier than might otherwise be necessary and might create undesired side-effects in some implementations.This issue proposes adding a new annotation to MicroProfile OpenAPI to allow (but not force) developers to declare which resources belong to which
Applications
.Possibilities:
@APIApplication
annotation which applies to subclasses ofApplication
:@APIResource
annotation which applies to subclasses ofApplication
:@APIResource
annotation which applies to JAX-RS resource classes:An advantage of the
@APIApplication
annotation is its consistency with other MP OpenAPI annotations which are typically named for the entity they describe (e.g.,@APIResponse
) with settings pertinent to that entity's OpenAPI behavior. This annotation would also be a convenient place to put any future OpenAPI-related attributes onApplication
s for which we might see a need.An advantage of
@APIApplication
and@APIResource
when applied to theApplication
subclass is that the declaration of the resources and the runtime manifestation (getClasses
and/orgetSingletons
) are syntactically close to each other and so more likely to be kept in sync.Disadvantages of any such new annotation:
getClasses
andgetSingletons
, meaning that the declared OpenAPI information and the runtime behavior are different.To help mitigate that, when otherwise invoking
Application
s'getClasses
andgetSingletons
methods during the normal course of runtime processing, the MicroProfile implementation could check that the classes and instances returned match the declared resources for that application, issuing a warning if they do not.(For some background, see #498)
The text was updated successfully, but these errors were encountered: