Duplicate Entries in Swagger

Question

I'm writing an API using the HalBuilder library for HAL representations.

As it stands now, I need to have two different methods for the JSON and HAL representations. As an example, my VersionResource includes the following two methods:

@GET
@ApiOperation(value = "Find all versions", response = Version.class, responseContainer = "List")
@Produces({MediaType.APPLICATION_JSON})
public Response getAsJson() {
    List<Version> versions = repository.selectAll();
    return Response.ok().entity(versions).build();
}

@GET
@ApiOperation(value = "Find all versions", notes="Returns HAL format", response = Representation.class, responseContainer = "List")
@Produces({RepresentationFactory.HAL_JSON})
public Representation getAsHalJson() {
    List<Version> versions = repository.selectAll();
    return this.versionRepresentationFactory.createResourceRepresentation(versions);
}

(Note: I'm sure there's a better way of collapsing these methods, and I'm looking into a way to do that)

But my immediate problem is that using two methods causes duplicate entries in my Swagger documentation:

Those two GET /versions are effectively the same thing, but they have different return types, so Swagger wants them to be different.

I'd like to collapse those two. What are my options here?

[It's probably worth pointing out that I'm using the Swagger Maven plugin to generate my documentation. The application is also using Guice for DI and Jersey for JSON representations.]

Answer 1

I read in https://github.com/swagger-api/swagger-spec/issues/146#issuecomment-59082475:

per design, we don't overload response type definitions for the same response code.

So I think the Maven plugin creates an invalid Swagger document.

What are your options?

• Be patient and watch these Swagger issues: https://github.com/swagger-api/swagger-spec/issues/146 and https://github.com/swagger-api/swagger-spec/issues/182
• Don't use Swagger