@Api.value as prefix to all operations path when using with JAXRS ?

[pierrecdn]

Using Swagger and Jersey, one problem when decoupling JAX-RS interfaces from implementation, is that you can't get consistent API Path in Swagger-UI.

Interface :

@Api(value = "/api/broadcasts", description = "Broadcast operations", protocols = "HTTP")
@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public interface Broadcast {
    /**
     * Retrieve a broadcast based on the channel ID and date
     */
    @GET
    @Path("/service/{serviceid}/{date}")
    @ApiOperation(value = "Get broadcast on Channel", notes = "Retrieve a broadcast based on the channel ID and date", httpMethod = "GET", response = BroadcastResponse.class)
    @ApiResponses(value = {
            @ApiResponse(code = HttpURLConnection.HTTP_ACCEPTED, message = "OK"), 
            @ApiResponse(code = HttpURLConnection.HTTP_NOT_FOUND, message = "Resource not found"), 
            @ApiResponse(code = HttpURLConnection.HTTP_INTERNAL_ERROR, message = "Internal error")
    })
    public BroadcastResponse getBroadcastByServiceDate(
            @ApiParam(value = "Channel ID", required = true) @NotNull @PathParam("serviceid") String serviceId, 
            @ApiParam(value = "Date of the broadcast", required = false) @PathParam("date") String date, 
            // vertx
            @Suspended final AsyncResponse response);

Implementation headers :

@Path("/api/broadcasts")
public class BroadcastImpl extends AbstractHandler implements Broadcast {
    @Override
    public BroadcastResponse getBroadcastByServiceDate(
            @NotNull String serviceId, 
            String date, 
            // vertx
            @Suspended final AsyncResponse response) {

will produce a Swagger JSON-file like this one :

"basePath" : "http://my.service.tld",
"resourcePath" : "/api/broadcasts",
"apis" : [ {
    "path" : "/service/{serviceid}/{date}",
    "operations" : [ {
      "method" : "GET",
      "summary" : "Get broadcast on Channel",
      "notes" : "Retrieve a broadcast based on the channel ID and date",

and will be displayed like this :

(Note that /service/{serviceid}/{date} is not the full path ; it should be /api/broadcasts/service/{service}/{date})

One solution I found was to set @path in both interface and implementation but it's not allowed in Jersey (crash when parsing) and in the JAX-RS Spec : https://java.net/jira/browse/JAX_RS_SPEC-19

So, maybe Swagger-UI should consider using @Api.value (resourcePath in the JSON file) to prefix each operation ?

[webron]

@pierrecdn - this is actually an issue related to swagger-core and not swagger-ui. Swagger-ui is completely unaware of your Java annotations and only deals with the output of swagger-core (or other libraries).

However, it does seem like a valid issue. Please reopen it on swagger-core's repo.