Issue with subresources not annotated with @Path

[GuiSim]

Hi !

If you have a resource such as:

@Path("test")
@Produces(MediaType.APPLICATION_JSON)
@Api("test")
public class TestResource
{
    @Path("/status")
    @GET
    @ApiOperation("Get status")
    public String getStatus()
    {
        return "{\"status\":\"OK!\"}";
    }

    @Path("/more")
    public TestSubResource getSubResource()
    {
        return new TestSubResource();
    }
}

and a subresource such as:

@Produces(MediaType.APPLICATION_JSON)
public class TestSubResource
{
    @Path("/otherStatus")
    @GET
    @ApiOperation("Get the other status!")
    public String otherStatus()
    {
        return "{\"a\":\"Still Ok!\"}";
    }
}

When accessing the Swagger spec under /api-docs/, you will get the following result:

{

    "apiVersion": "v9",
    "swaggerVersion": "1.2",
    "apis": [
        {
           "path": "/test"
        }
    ]
}

Under /api-docs/test you will get the following result:

{

    "apiVersion": "v9",
    "swaggerVersion": "1.2",
    "basePath": "/rest",
    "resourcePath": "/test",
    "produces": [
        "application/json"
    ],
    "apis": [
        {
            "path": "/test/status",
            "operations": [
                {
                    "method": "GET",
                    "summary": "Get status",
                    "notes": "",
                    "type": "void",
                    "nickname": "getStatus",
                    "parameters": [ ]
                }
            ]
        }
    ]

}

As you can see, the /test/more/otherStatus method is not documented in the Swagger spec.

Adding the @Api annotation on the TestSubResource sub resource fixes the issue but introduces a new one. Now the calls are documented correctly in /api-docs/test BUT the methods under the TestSubResource resource are visible under /api-docs.

This should not be the case as example.org/more/otherStatus is not a valid API call. It is only accessible through the TestResource resource using example.org/test/more/otherStatus.

EDIT: typos

[GuiSim]

I feel that a @ApiSubResource annotation would resolve the issue.
It would be excluded from root apis but would still be scanned by the scanner.

[jayzaw]

Ran into the same issue, GuiSim may be right, but I leave that to you guys. I think it shouldnt be necessary to annotate SubResources as such

[jayzaw]

I had another issue related to this one I think, so I post it into here:

Main resource A, Sub resource B
A has B linked into it
Path of A is /site
Path of B is /site/{siteId}/driver

Sub resource B has a resource C linked to it, accessible through:
/site/{siteId}/driver/driverId/car

A POST operation "O" in C has the path:
/site/{siteId}/driver/driverId/car/

The problem here is that swagger wont recognize that I have 2 path parameter variables in there which need to be specified in order to reach the operation. It just "notices" one of them (driverId).

As a workaround, I had to specify the path parameter siteId in the "O" operation in C with ApiImplicitParams. This then worked.

[fehguy]

The @Api(hidden = true) has been added in 1.3.8. See sample here:

https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs-subresource

[fehguy]

this should be fixed in 1.3.8. You can add a "hidden" value to the @Api operation to hide the resource completely, except in the case of being a subresource.