How to use @Api swagger annotation in sub-resource class?

Question

In my project I have some sub-resources, correctly implemented according to the Jersey framework guidelines.

However, I have a problem in generating the openapi.json file (generated by swagger-maven-plugin). In particular, I would like to be able to use the @Api swagger annotation on classes that implement sub-resources, to apply some properties, such as authorizations.

The problem is that if I use the @Api annotation on the sub-resource classes, swagger sees those classes not only as a sub-resources, but also as resources. The result is that in the openapi.json file, for each sub-resource, a same resource is generated (which should not exist).

The root resource:

@Path("root")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Api(value = "/root", authorizations = {
        @Authorization(value = "auth", scopes = {})
})
public class ExperienceResource {

    @Path("/sub_a")
    public SubResourceA getSubA() {
        return new SubResourceA();
    }

    @Path("/sub_b")
    public SubResourceB getSubB() {
        return new SubResourceB();
    }
}

The sub-resource:

@Api(authorizations = {
     @Authorization(value = "auth", scopes = {})
})
public class SubResourceA {

    @GET
    ...
}

I also tried using @Api(value="") or @Api(value="sub_a"), but they don't work or make things worse. Obviously, if I remove the @Api annotation everything works correctly, but I am forced to apply the properties operation by operation.

Any suggestions?

Answer 1

The solution was quite simple. To ensure that the class that implements the sub-resource is seen by swagger just as a sub-resource (and not as a resource too) just add the property hidden = true in the @Api annotation

   @Api(hidden = true, authorizations = {
     @Authorization(value = "auth", scopes = {})
})
public class SubResourceA {

    @GET
    ...
}