Support for Subresource Locators

[miketzian]

Swagger does not currently support Subresource locators, as per jax-rs 1.1:

http://jsr311.java.net/nonav/releases/1.1/spec/spec3.html#x3-310003.4.1

I propose a new annotation to handle the definition of a sub resource, similar to how resources are currently defined.

@Api(value = "/some-resource", description = "Info about some resource")
public class SomeResource {

    @Path("/{resourceId}/some-sub-resource")
    @ApiResource(value = "/{resourceId}/some-sub-resource" resourceClass="com.foo.SomeSubResource")
    public SomeSubResource getSubResource(@PathParam("resourceId") String resourceId) {
        return new SomeSubResource(resourceId)
    }
}

The current ApiReader (com.wordnik.swagger.core.ApiReader.scala:213) disregards any method which does not define an ApiOperation (as it should), and as a result does not show any information about sub resources.

I use sub resources for a variety of things, generally providing a sort of filter on a main resource. Lets say you have a customer resource, and an order resource

GET /customers
GET /customers/{customerId}
GET /orders
GET /orders/{orderId}

A sub resource locator is then used to return a customer resource which only relates to those customers attached to a particular order, like such :

GET /orders/{orderId}/customers

Which then provides access to the customer resource methods, like:

GET /orders/{orderId}/customers/{customerId}

This is incredibly useful and I've used this to simplify our jax-rs implemention fairly significantly.

Keen to hear thoughts on how this would / should work, and will spend some time on a potential implementation this am.

Cheers

Mike

[miketzian]

My take on the implementation - working well internally.

https://github.com/mdekmetzian/swagger-core/compare/issue-102

[JoshP]

Any plans to use mdekmetzian's implemetation?

[miketzian]

FWIW @JoshP, we're using the fork as re-implementing everything multiple times just isn't worth it

[ghost]

+1 on this issue.

[konrade]

+1 to get in!

[iesen]

+1..really blocker to add our prod toolset

[fehguy]

I'm almost done with the next version and would like to get this in. If someone can produce a sample without Swagger integration, I can try to make it happen.

[lisbakke]

Hello -- Just here to +1 this, as well. My team will have to use this patched swagger in a local maven repository until this is merged.

Thanks!

[lisbakke]

Also, what kind of sample are you looking for?

[fehguy]

If you can just make a simple java sample of how resource locaters are needed, without any swagger support, i can see if it can fit in.

[lisbakke]

Our use case is the same as what @mdekmetzian described (and has some pseudocode for).

We have resources such as:
CustomersResource.java
CustomerResource.java
OrdersResource.java
OrderResource.java

This would be a valid request:
/customers/{id}/orders

CustomersResource would handle /customers/{id} and return a CustomerResource for that customer. CustomerResource would handle /orders and return OrdersResource. OrdersResource would get the orders for that customer.

Is code needed to clarify why or how this is done?

[fehguy]

formal support will come fastest with a simple working sample :)

[miketzian]

There you go @fehguy, knocked together an extremely simple working sample ;)

https://github.com/mdekmetzian/subresource_example

[fehguy]

great, thanks!

[fehguy]

OK, I sent a pull request. I think you'll find the solution elegant, please see that I covered all your use cases. Essentially, we scan the return type from the method (which must be annotated with @ApiOperation) and if the class is annotated with @Api annotations, we treat it as a subresource.

This is all based on the 1.3.0-SNAPSHOT which has been totally refactored.

[fehguy]

pushed to 1.3.0-SNAPSHOT and shown in this example:

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

[jmarreroc]

Hello!

I'm trying to adjust my resources hierarchy (who describes a tree morphology) as related on Subresource locators support for jax-rs 1.1 (as mdekmetzian mentioned) :
http://jsr311.java.net/nonav/releases/1.1/spec/spec3.html#x3-310003.4.1

So, i have a Resource:

@Path("resource")
@Produces("application/json")
@Api(value="resource")
public class Resource {

    @GET
    @ApiOperation( ... )
    public Resource get() {
        return this;
    }

    @Path("/{subresource}")
    public SubResource get(@PathParam("subresource") String subresource) {      
        return new SubResource(subresource);        
    }
}

And a set of subresources describing a tree form (as showns this simple example), with no '@path' class annotation defined as mentioned in http://jsr311.java.net/nonav/releases/1.1/spec/spec3.html#x3-310003.4.1 subresource specification (specifically in the WidgetResource definition):

@Produces("application/json")
//@Api <-- tried but doesn't work
public class SubResource {

    @GET
    @ApiOperation( ... ) //???
    public SubResource get() {
        return this;
    }

    @Path("/items")
    public OtherResource items(...) {       
        return new OtherResource(...);      
    }
}

I read all posts and see the examples attached but... finally i can say that i didn't understand how to document my resource hierarchy with swagger, (or if it's now supported) and nobody talks at this respect. All I see in the example provided (https://github.com/mdekmetzian/subresource_example) is that both resources '/pet' and '/owner' have their own @path definition, so both are considered as resorurces who hang from root '/' and that isn't my scenario. So if I annotate all my resource classes whith @path, i loose the resource exploration support dinamically provided by Jax-rs. What i'm doing wrong?! I just type directly in the browser the URIS and can navigate perfectly all resources hierarchy but cannot provide correctly the documentation to swagger.

Thank you for your time!

[jmarreroc]

Also tried to include the @ApiOperation as mentioned fehguy over the subresource construction method but finally I get in the UI : "SwaggerOperation " + nickname + " is missing method"

@Path("resource")
@Produces("application/json")
@Api(value="resource")
public class Resource {

    @GET
    @ApiOperation( ... )
    public Resource get() {
        return this;
    }

    @ApiOperation( ... )
    @Path("/{subresource}")
    public SubResource get(@PathParam("subresource") String subresource) {      
        return new SubResource(subresource);        
    }
}

@Produces("application/json")
@Api(value="subresource") // tried but doesn't work
public class SubResource {

    @GET
    @ApiOperation( ... ) //???
    public SubResource get() {
        return this;
    }

    @Path("/items")
    public OtherResource items(...) {       
        return new OtherResource(...);      
    }
}

I'm using Swagger 2.11 : (bundle version 1.3.10)