Annotations on concrete class/methods are ignored

[rohitsanj]

Hi! I'm trying to add microprofile openapi annotations to an implementation class (and it's @Override methods), with the intention for these annotations being added to the existing set of annotations on the underlying interface. However, these annotations are ignored and do not get picked up in the OpenAPI spec.

I'm not sure if this is a limitation of the Java language itself, or if it's something this library does not support, or if it's a bug! I've described in detail what I'm trying to accomplish below:

Consider this Java interface that declares some route handlers (I guess Quarkus/microprofile does some magic to generate the OpenAPI spec from these annotations)

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.Response;

@Path("/foo/bar")
public interface FooResource {
  @GET
  Response getBar();
}

Concrete implementation of the interface above,

import org.eclipse.microprofile.openapi.annotations.enums.ParameterIn;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

@Tag(name = "Foo Resource") // ignored
public class FooResourceImpl implements FooResource {
  @Parameter(name = "x-connection-id", in = ParameterIn.HEADER, required = true) // ignored
  @Override
  public Response getBar() {
    // bla
  }
}

For more context about the project I'm currently working on: since the resource interfaces are generated from an OpenAPI spec, it's not straightforward to simply add the openapi annotations onto the interface directly.

Hoping to engage the community here to find a path forward, thanks!

[Azquelt]

This is the repository for the specification, not for any specific implementation. You might want to open an issue against whichever implementation you're using (probably smallrye-open-api since you mentioned Quarkus).

The spec is extremely vague on where annotations can be used and how they should be interpreted and as such is completely silent on whether putting MP OpenAPI annotations on the method implementation when there are Jakarta REST annotations on the interface is allowed.

I note that Jakarta REST allows annotations from interfaces to be inherited, as long as there are no Jakarta REST annotations at all on the implementation method. I think it would be reasonable for MP OpenAPI to specify either way whether its annotations must be alongside the relevant Jakarta REST annotations or whether they can be split, but currently it does neither.

I don't think we have any tests in the TCK where Jakarta REST annotations are inherited.

When deciding what we should specify here, we should note that Jakarta REST recommends against relying on annotation inheritance:

For consistency with other Jakarta EE specifications, it is recommended to always repeat annotations instead of relying on annotation inheritance.

[Azquelt]

For more context about the project I'm currently working on: since the resource interfaces are generated from an OpenAPI spec, it's not straightforward to simply add the openapi annotations onto the interface directly.

Does this mean you already have a complete OpenAPI spec for your API? Can you include your existing OpenAPI spec in the application and avoid needing to add annotations altogether? (Maybe even disable scanning of your classes.)