java - 使用 swagger UI 记录包装的 REST 响应

Question

我有一个 WidgetDto，我已经用 swagger UI 注释进行了注释。最终响应用一层元数据包装 WidgetDto 列表(每页 21 of this RESTful 最佳实践文档)。例如:

{
  "data" : [ 
    {
      "id" : 1234,
      "prop1" : "val1"
      ...
    },
    {
      "id" : 5678,
      "prop1" : "val2"
      ...
    }, 
    ...
  ]
}

我的 java 代码如下所示:

@GET
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(
        value = "Get all widgets.",
        response = WidgetDto.class
)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Returns the list of widgets.")
})
public Response getWidgets() {
  List<WidgetDto> widgets;
  ...
  Map<String, Object> responseBody = new HashMap<>();
  responseBody.put("data", widgets);
  return Response.ok(responseBody).build();
}

我想在多个资源上重用这个模式，我不想为每个响应类型创建列表 DTO。有没有一种优雅的方法可以使用 swagger 来记录这些类型的响应主体？

Answer 1

您的元数据不是资源的一部分，但它是资源表示的一部分。

在我的例子中，响应类型是“application/hal+json” ' 和 'application/json'，它们中的每一个都使用具有不同元数据的不同包装器。为了解决这个问题，我创建了一个 extern 文档来解释这两个包装器以及每个包装器如何用元数据表示单个资源和资源列表。

我认为我的选择是正确的，因为我将资源与其表示分开(根据 this RESTful 最佳实践文档的第 7 页“通过表示操作资源”)

在您的情况下，您返回一个 WidgetDto 列表，元数据层是您资源表示的一部分。

但是，您可以使用通用类，例如 spring-hateoas 使用的 Resource 和 Resources | :

public class Resources<T> implements Iterable<T>  {
    private final Collection<T> content;
    Resources(Iterable<T> content) {
        this.content = new ArrayList<T>();
        for (T element : content) {
            this.content.add(element);
        }
    }
}

然后像这样使用它:

@GET
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(
        value = "Get all widgets.",
        response = WidgetDto.class
)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Returns the list of widgets.")
})
public Response getWidgets() {
  List<WidgetDto> widgets;
  ...
  return Response.ok(new Resources<WidgetDto>(widgets)).build();
}