google云端点主体数组

Question

我们有一个用Java编写的rest API (托管在Wildfly中)。我们的服务在kubernetes (GKE)中运行。我们希望利用云端点来跟踪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个方法，这些方法在主体参数中包含一个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

我在Endpoint中遇到过完全相同的问题，它似乎不认为传递对象数组作为主体参数是有效的。我只使用了一个通用对象和一个像样的描述来解决这个问题。描述不会以编程方式修复任何东西，但是使用泛型对象允许端点工作，并且描述为API的使用者提供了预期的信息。

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

这似乎是Endpoint团队的疏忽，因为在主体中使用对象数组非常符合OpenApi规范，并且可以与http://editor.swagger.io/等工具配合使用

编辑：我还应该补充说，仅使用原始数组作为请求正文或响应正文通常是不好的做法，因为如果将来需要其他属性，例如计数或分页信息，这可能会导致约定破坏更改。

如果这是一个现有的API，并且您只是记录了现有的合同，那么这个解决方案将会完成工作，但是如果您正在设计一个新的API，那么一个更好的定义应该是：

parameters:
  - in: body
    name: body
    description: All the FooBar objects
    required: false
    schema:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/definitions/FooBarResource'

因为稍后可以对其进行扩展以添加其他属性，如

parameters:
  - in: body
    name: body
    description: All the FooBar objects
    required: false
    schema:
      type: object
      properties:
        count:
          type: integer
          description: The total count of resources
        callbackUrl:
          type: string
          description: The URL to trigger once creation is complete
        items:
          type: array
          items:
            $ref: '#/definitions/FooBarResource'
          description: The resources to create

Answer 2

你可以比一个普通的对象做得更好。Y您可以指定一个数组作为具有单个键的对象的值。这样您就可以保留您的类型信息：

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"

它很难看，但至少它记录了您传递的模型应该是什么样子。