Swagger中的重复条目

Question

我正在使用HalBuilder库为HAL表示编写API。

现在，我需要为JSON和HAL表示提供两种不同的方法。例如，我的VersionResource包含以下两种方法：

@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);
}

（注意：我确信有更好的方法来折叠这些方法，我正在研究如何做到这一点）

但我的直接问题是使用两种方法会导致我的Swagger文档中出现重复的条目：

这两个GET /versions实际上是相同的，但它们有不同的返回类型，因此Swagger希望它们不同。

我想把这两个崩溃。我有什么选择？

[可能值得指出我正在使用Swagger Maven插件来生成我的文档。该应用程序还使用Guice for DI和Jersey进行JSON表示。]

Answer 1

我读了https://github.com/swagger-api/swagger-spec/issues/146#issuecomment-59082475：

  

根据设计，我们不会为相同的响应代码重载响应类型定义。

所以我认为Maven插件会创建一个无效的Swagger文档。

你有什么选择？

• 请耐心等待，并观看这些Swagger问题：https://github.com/swagger-api/swagger-spec/issues/146和https://github.com/swagger-api/swagger-spec/issues/182
• 不要使用Swagger