API Mapping

[Ron R]

One of our API requirements is to have a set of similar API calls for different entity types in our application (among other non-similar calls).

In order to reduce code duplication, we have something along the following lines:

public abstract class BaseRestService<T> {
    @GET
    @Path("/{id}")
    public Response getSpecific(@PathParam("id") String id) { ... }
}

@Path("/entityA"}
public class EntityARestService extends BaseRestService<EntityA> {}

@Path("/entityB"}
public class EntityBRestService extends BaseRestService<EntityB> {}

The question is obvious - can Swagger process such API calls? I certainly hope the answer would be yes, without having to override the API calls in each extending class only to call the super() implementation. This of course will require the API description to be dynamic to an extent.


The second issue on this matter is class-level @PathParam's. According to the JAX-RS spec, the following code is acceptable:

@Path("/base")
public class RestService {
    @QueryParam("limit")
    private int limit;
 
    @Path("/listA")
    @GET
    public List<Foo> listA() {} 

    @Path("/listB")
    @GET
    public List<Foo> listB() {}
}

In this sample code, the query parameter "limit" will be available in both listA() and listB() API calls.
Swagger's @ApiParam annotation has the target of Parameter and thus cannot be used on class members.
Are there any future plans to allow adding the annotation on class members as well?
Please note that I'm not saying that this is a good architecture (not saying it's a bad one either), however it is valid to the JAX-RS spec and I believe Swagger should support it assuming one of the goals is to allow easy documentation generation for JAX-RS based applications.

[tony tam]

Hi Ron, great questions.  We do support such overrides, and our sample projects actually demonstrate it.

For instance, in java-jaxrs sample:

public class PetStoreResource extends JavaHelp

contains all the logic for the PetStore API.  We then extend that class and assign it to different media types:

@Path("/store.json")

@Api(value="/store" , description = "Operations about store")

@Produces({"application/json"})

public class PetStoreResourceJSON extends PetStoreResource

and

@Path("/store.xml")

@Singleton

@Api(value="/store", description = "Operations about store")

@Produces({"application/xml"})

public class PetStoreResourceXML extends PetStoreResource

You just state that each subclass has a different media type and you're good.  All of our APIs are written this way.

I'm not positive about the @QueryParam example you gave.  I'll give that a test and post back.

Tony