Subresource scanning based on @ApiOperation

[shivangshah]

Per discussions on #925 with @fehguy , creating new issue.

Through a subresource, if a path is not given at root level (because it gets subresource'd from inheritance), the api will not show up in swagger. For example:

@Path("/api/v1")
@Api(tags = "V1 APIs - All", value = "/api/v1", description = "MDM Services")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class BaseResource {

@Path("/somePath")
    @ApiOperation(value = "Returns Some service", response = SomeResource.class)
    public SomeResource getSomeService() {
        return this.someService;
    }
}
@Api(tags = "V1 Tenant APIs", hidden = true, value = "/tenants", description = "MDM Base Service")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class SomeResource {
@GET
    @Path("")
    @CacheControl(maxAge = 3, maxAgeUnit = TimeUnit.SECONDS)
    @ApiOperation(value = "get tenants", notes = "Sort Order Values can be 'ASC' or 'DESC'", response = String.class)
    public Response getStuff(@ApiParam(value = DATASOURCE_HEADER, required = true)
{
}

had to provide @path("") for the swagger scanner to pickup that api. Otherwise it did not recognize the inherited path

[jmarreroc]

I feel that the first @ApiOperation :

@Path("/somePath")
@ApiOperation(value = "Returns Some service", response = SomeResource.class)
public SomeResource getSomeService() {
   return this.someService;
}

Maybe could be removed as you defined the @ApiOperation on the GET of the scanned @path("/somePath") resource, which define:

@GET
@Path("")
@CacheControl(maxAge = 3, maxAgeUnit = TimeUnit.SECONDS)
@ApiOperation(value = "get tenants", notes = "Sort Order Values can be 'ASC' or 'DESC'", response = String.class)
public Response getStuff(@ApiParam(value = DATASOURCE_HEADER, required = true) { ... }

So... In this case, what documentation would shown? "Returns Some service", "get tenants" or both...
I think that its the same path with two documentation definitions

[shivangshah]

@jmarreroc Not sure I understand. The first @path("/somePath") is basically returning a subresource while the second @path("") is just for swagger to scan and pick up that specific subresource method (yes, with the same path). The difference is we don't provide an HTTP method when a subresource is returned. JAX-RS won't understand a @get on a subresource (although I haven't tried it first hand but that's what i'd expect)

The "returns some service" api operation actually doesn't do anything from what I can see. It's just a way to let swagger know that this is a subresource and you need to go inside this subresource class to scan the remaining methods (and corresponding paths). So you will only see the documentation for "getTenants" (as expected)

[jmarreroc]

Ok, so finally swagger shown only the documentation defined over the HTTP method. Thx!

[shivangshah]

That's what I found so far .. yes ! And no problem.

[fehguy]

this is fixed in develop_2.0

[shivangshah]

@fehguy Thank you ! Which snapshot/release I can test this with ?

[fehguy]

If you wait a few, there will be a formal release. I'm verifying for 1.5.0-M2 right now.

[shivangshah]

sounds good .. let me know what release .. currently I am on 1.5.4-Snapshot

[webron]

@shivangshah - it was indeed released under 1.5.0-M2.

[shivangshah]

@webron @fehguy I just tried with 1.5.0-M2. The bug is still there. I had to give @path("") for the scanner to pick it up the subresource method even though there is an @ApiOperation

[webron]

@shivangshah - this should be fixed in develop_2.0 now. Can you try?

[shivangshah]

@webron do you know which snapshot i can test it with instead of branch? (I might not be able to clone the branch and test :( )

[webron]

@shivangshah I don't think we have a published snapshot for it yet, so you'd have to build it on your own.

[shivangshah]

@webron I see ok .. when I get a chance, I will build and try it out ..

[shivangshah]

Sorry for the late response @webron @fehguy . I just got around testing this on 1.5.0 release and it still does not work .. :(

[webron]

@shivangshah - I'm afraid that at this point you'd have to provide us with a sample project that mimics the problem for us to further investigate.

[shivangshah]

@webron Let me set one up and send you guys the link soon ..

[MichaelVoegeli]

Is there still the lack of the example project? It still doen't work.

[defnull]

Running into the same problem. Only the most trivial kind of JAX-RS application seems to be supported.

[webron]

Which version are you using?

[MichaelVoegeli]

We are using the swagger-maven-plugin version 3.1.3 that is using swagger version 1.5.4 to document our REST services. I hope it's not a bug of the maven plugin itself and should be addressed there.

[defnull]

Okay, after removing all the @Api and @Api(hidden=True) annotations it worked as intended. Looks like I was just misguided by google and old workarounds/examples still floating around. Sorry for the noise.

If someone finds this via google: Resource locator methods do not need any swagger-specific annotation, only @Path. Sub-Resources classes do not need any annotation at all (No empty @Path and no @Api and especially no @Api(hidden=true)). Swagger will pick them up when it finds a @Path annotated sub-resource locator method.

Here is a working example:

@Path("/")
public class RootResource {
    @GET
    @ApiOperation("Service info")
    public String info() {
        return "info";
    }

    @Path("/subresource")
    public SubResoure subResourceLocator() {
        return new SubResoure();
    }
}

public class SubResoure {
    @GET
    public String info() {
        return "sub";
    }
}