Why are some sub-resources ignored?

[cristalp]

We have a couple of people in our team who love JAX-RS sub-resources. In very simple cases, the scanner can pick up the information, and everything is added to openapi.json. In other cases however, the sub-resource in a REST class is ignored completely or the whole sub-resource as a class is ignored completely.

Is there some rule to how much sub-resources are supported? Is there some way to debug the scanner?

[MikeEdgar]

They should be found, but without an example I can't diagnose for sure. Possibly the return type of a resource class somewhere doesn't allow the scanner to find the sub-resource.

[cristalp]

OK, here we go. I just want to emphasize that this is not my code :-) Also, I have made things simpler and they don't make much sense.

public class Thing {

  public Integer getID() {
    return 1;
  }

  public Integer getFirst() {
    return 3;
  }

  public Integer getSecond() {
    return 4;
  }
}

public class ThingService {

  public Thing getThing(final Integer id) {
    return null;
  }

  public List<Thing> getThings(final Integer id, final Integer first) {
    return null;
  }
}

public class CompoundID {

  private Integer first;

  private Integer second;

  private CompoundID(final Integer first, final Integer second) {
    super();
    this.first = first;
    this.second = second;
  }

  public static CompoundID create(final Integer first, final Integer second) {
    return new CompoundID(first, second);
  }

  public Integer getFirst() {
    return this.first;
  }

  public Integer getSecond() {
    return this.second;
  }
}

public class ResourceOne {

  private Integer id;

  @Inject
  private Provider<ResourceTwo> resourceTwo;

  @Inject
  private ThingService thingService;

  public void setId(final Integer id) {
    this.id = id;
  }

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(summary = "Shows something")
  public String show() {
    return null;
  }

  @GET
  @Path("id")
  @Produces({ MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON })
  @Operation(summary = "Shows the ID")
  public Integer showId() {
    return this.id;
  }

  @Path("two")
  public ResourceTwo locateTwo() {
    final Thing t = this.thingService.getThing(this.id);
    final ResourceTwo two = this.resourceTwo.get();
    two.setCompoundID(CompoundID.create(t.getFirst(), t.getSecond()));
    return two;
  }
}

public class ResourceTwo {

  private CompoundID compoundID;

  @Inject
  private Provider<ResourceOne> resourceOne;

  @Inject
  private ThingService thingService;

  public void setCompoundID(final CompoundID compoundID) {
    this.compoundID = compoundID;
  }

  private CompoundID getCompoundID() {
    return this.compoundID;
  }

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(summary = "Shows whatever")
  public String show() {
    return getCompoundID().toString();
  }

  @GET
  @Path("id")
  @Produces({ MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON })
  @Operation(summary = "Shows the ID")
  public String showId() {
    return getCompoundID().toString();
  }

  @GET
  @Path("count")
  @Produces({ MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON })
  @Operation(summary = "Gets the size")
  @APIResponses(value = { @APIResponse(responseCode = "200", description = "Die Anzahl Gebühren") })
  public int count() {
    return read().size();
  }

  @Path("{idx}")
  @Operation(summary = "Gets the nth thing")
  public ResourceOne locateOne(@PathParam("idx") final Integer idx) {
    final List<Thing> g = read();
    final int count = g.size();
    final Integer id = g.get((count + idx) % count).getID();
    final ResourceOne one = this.resourceOne.get();
    one.setId(id);
    return one;
  }

  private List<Thing> read() {
    final CompoundID id = this.getCompoundID();
    return this.thingService.getThings(id.getSecond(), id.getFirst());
  }
}

@Path("/")
public class SuperResource {

  @Inject
  private Provider<ResourceOne> resourceOne;

  @Inject
  private Provider<ResourceTwo> resourceTwo;

  @Path("/object")
  @Operation(summary = "Gets the object")
  public Object getObject(@Parameter(required = false, description = "The ID") @MatrixParam("id") final Integer id,
      @Parameter(required = false, description = "The compound ID") @MatrixParam("compound") final CompoundID compundId) {
    return compundId == null ? getOne(id) : getTwo(compundId);
  }

  private Object getOne(final Integer id) {
    final ResourceOne o = this.resourceOne.get();
    o.setId(id);
    return o;
  }

  private Object getTwo(final CompoundID id) {
    final ResourceTwo o = this.resourceTwo.get();
    o.setCompoundID(id);
    return o;
  }
}

[MikeEdgar]

The issue is definitely that SuperResource#getObject returns an Object. The scanner isn't able to identify ResourceOne or ResourceTwo with that return type. Let me think if there's a way to manage this...

[cristalp]

Do you have any update on this?

[MikeEdgar]

I'm not sure there is any way to resolve this unfortunately. Aside from not knowing the possible classes that could be returned by SuperResource#getObject, even if we did know them, there is a problem where path conflicts could exist.

For example, both ResourceOne and ResourceTwo have GET and GET {id} operations. Presumably these are two different operations that you want in your OpenAPI, but it's not possible since paths must be unique. Are they logically the same operation, just with two different implementations?

Can you define an interface with the information you want in the OpenAPI definition and use that for the return type instead of Object?

[cristalp]

Well, to be honest, this is not the way that I would implement things :-) IMHO it's just implementing endpoints in a complicated way.
And I see what the problem is with the endpoint paths. But I can't change the software, mainly because it's not "mine".

Thus, let's just leave this unanswered, and those endpoints will then not appear, c'est la vie!

Thanks for your help!