Question

我们有一个用Java编写的rest API（在Wildfly中托管）。我们的服务在kubernetes（GKE）运行。我们希望利用Cloud Endpoints来跟踪API的使用情况和响应能力。 API不是新的，我们已经提供与其交互多年的软件。它也很大（成千上万的公共方法）。我们有API的Swagger文档，没有验证错误。当我尝试使用：

部署我们的Swagger时

gcloud beta service-management deploy swagger.yaml

不成功。我得到以下错误重复237次：

ERROR: unknown location: http: body field path 'body' must be a non-repeated message.

我已将其跟踪到237个方法，其中包含body参数中的json数组。在我们的API中，这些是接受或返回对象列表的方法。有什么方法可以让service-management deploy接受这个吗？更改我们的API不是一种选择，但我们真的希望能够使用端点。

例如，此方法签名：

@PUT
@Path ("/foobars/undelete")
@Consumes (MediaType.APPLICATION_JSON)
@Produces (MediaType.APPLICATION_JSON)
@ApiOperation (value = "Undelete foobars")
@ApiResponses (value =
{
    @ApiResponse (
        code              = 200,
        message           = "foobars undeleted",
        response          = FooBar.class,
        responseContainer = "List"
    ) , @ApiResponse (
        code              = 206,
        message           = "Not all foobars undeleted",
        response          = FooBar.class,
        responseContainer = "List"
    ) , @ApiResponse (
        code              = 410,
        message           = "Not found"
    ) , @ApiResponse (
        code              = 500,
        message           = "Server Error"
    )
})
public Response undeleteFooBars (@ApiParam (value = "FooBar ID List") List<UUID> entityIds)

生成此swagger片段：

"/foobars/undelete":
    put:
      tags:
      - foo
      summary: Undelete FooBars
      description: ''
      operationId: undeleteFooBars
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: FooBar ID List
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      responses:
        '200':
          description: Foo Bars undeleted
          schema:
            type: array
            items:
              "$ref": "#/definitions/FooBar"
        '206':
          description: Not all FooBars undeleted
          schema:
            type: array
            items:
              "$ref": "#/definitions/FooBar"
        '410':
          description: Not found
        '500':
          description: Server Error

Answer 1

我遇到了与端点完全相同的问题，它似乎并不认为传递对象数组作为body参数有效。我通过使用通用对象和体面描述来解决这个问题。该描述不会以编程方式修复任何内容，但使用通用对象允许端点工作，并且描述为API的消费者提供了预期的信息。

parameters:
  - in: body
    name: body
    description: Array of FooBar objects
    required: false
    schema:
      type: object

这似乎是对端点团队恕我直言的疏忽，因为在OpenApi规范中使用正文中的对象数组可以很好地使用http://editor.swagger.io/等工具

Answer 2

您可以做得比普通对象还要好。您可以使用单个键将数组指定为对象的值。这样可以保留类型信息：

parameters:
     - description: "Your items to add"
       in: body
       name: listings
       required: true
       schema:
         type: object
         properties:
           payload:
             type: array
             maxItems: 1000
             minItems: 1
             $ref: "#/definitions/listing"

这很丑陋，但至少它记录了您要传递的模型应该是什么样子。

谷歌云端点正文数组

2 个答案: