java - 如何将响应实体封装到 Swagger 中的主模板响应中？

Question

我的问题与 posted here 相关.

我不得不重新表述我的问题，因为我觉得之前的问题太冗长了。再次尝试一下!

我有一个 REST API，它返回 Assets 列表，其编码如下:

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Response getAllAssets() {
        List<Asset> assets = new ArrayList<Asset>();
        for(int i=1; i<11; i++) {
            assets.add(new Asset(i));
        }

        return RestResponse.create(Status.OK, "10 assets Fetched successfully!", assets);
    }

它生成的响应是这样的:

{
    "message":"10 assets Fetched successfully!",
    "content": [{
        "id":"1",
        "type":"LPTP",
        "owner":"Ram",
        "serialNo":"WDKLL3234K3",
        "purchasedOn":"01 Jan 2017"

    },
    {
        "id":"2",
        "type":"LPTP",
        "owner":"Ram",
        "serialNo":"WDKLL3234K3",
        "purchasedOn":"01 Jan 2017"

    },
    ...
    ]
}

我的应用程序中有超过 60 个服务，它们遵循相同的响应模板:

{
        "message":"Message the service wants to send to the client",
        "content": {
            ....
            Entity returned by the service
            ....
        }
}

以下是代表我们的响应模板的 RestResponse POJO:

 public class RestResponse {
        private String message;
        private Object content;

        public String getMessage() {
            return message;
        }
        public void setMessage(String message) {
            this.message = message;
        }
        public Object getContent() {
            return content;
        }
        public void setContent(Object content) {
            this.content = content;
        }

        private RestResponse(String message, Object content) {
            this.message = message;
            this.content = content;
        }

        public static Response create(Response.Status status, String message, Object content) {
            return Response.status(status).entity(new RestResponse(message, content)).build();
        }
}

现在我们正在使用 Swagger 记录所有 API，但遇到了问题。

由于我们要返回 RestResponse对于我们所有的 API 的类，我为我的操作编写了以下注释:

@ApiOperation(value="Fetches all available assets", response=RestResponse.class, responseContainer="List")

Swagger 的作用是在 RestResponse 类的定义架构中，如下所示:

"definitions": {
    "RestResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "content": {
          "type": "object"
        }
      }
    }
 }

在这里，我没有获得有关 content 内对象属性的任何信息或模式。属性(property)。

我理解这是因为 Swagger 不适用于通用对象。

所以如果我改变我的@ApiOperation下面的注释:

@ApiOperation(value="Fetches all available assets", response=Asset.class, responseContainer="List")

在上面的例子中，Swagger 描述了 Asset 的属性实体，但显然，message (我的回复模板的)属性丢失。

我的问题是我想两者兼得。 content我的响应模板的属性可以是任何实体。

那么，我可以设置 response=Asset.class并指示 Swagger 附上 Asset到RestResponse content属性(property)先于文件吗？或者我可以通过其他方式实现这一目标吗？

希望这次我是准确的!

谢谢，斯里拉姆·斯里达兰。

编辑 - 在我尝试了 Marc Nuri 的建议后我创建了一个类似的RestServiceResponse.class使用通用对象，并设置 responseReference我的 @ApiOperation 的属性至RestServiceResponse<Asset> 。下面是我得到的 JSON。

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": ""
  },
  "host": "localhost:7070",
  "basePath": "/assets/rest",
  "tags": [
    {
      "name": "Assets"
    }
  ],
  "schemes": [
    "http"
  ],
  "paths": {
    "/assets/{id}": {
      "get": {
        "tags": [
          "Assets"
        ],
        "summary": "Fetches information about a single asset",
        "description": "",
        "operationId": "fetchAssetDetail",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "$ref": "#/definitions/RestServiceResponse<Asset>"
            }
          }
        }
      }
    }
  }
}

如您所见，Definitions部分完全丢失。我错过了什么吗？

我有我的project in GitHub ，以防您需要查看整个代码。请帮助我。

Answer 1

我们在微服务响应中使用类似的结构。

唯一的区别是我们的响应容器(即 RestResponse)没有原始类型，并使用消息正文/内容的 Type 参数。

请尝试将您的 RestResponse 更改为:

public class RestResponse<T> {
    private String message;
    private T content;

    public String getMessage() {
        return message;
    }
    public void setMessage(String message) {
        this.message = message;
    }
    public T getContent() {
        return content;
    }
    public void setContent(T content) {
        this.content = content;
    }

    private RestResponse(String message, T content) {
        this.message = message;
        this.content = content;
    }

    public static <T> Response create(Response.Status status, String message, Object content) {
        return Response.status(status).entity(new RestResponse(message, content)).build();
    }
}

然后像这样注释您的端点:

 @ApiOperation(
            value="Fetches all available assets",
            responseReference = "RestResponse<List<Asset>>")

这对于最新版本的 swagger 来说工作正常。