java - 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 进行 DI 和 Jersey 进行 JSON 表示。]

Answer 1

我读到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.

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

你有什么选择？

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