google-app-engine - 谷歌云端点主体阵列

Question

我们有一个用 Java 编写的 rest API(托管在 Wildfly 中)。我们的服务在 kubernetes (GKE) 中运行。我们希望利用 Cloud Endpoints 来跟踪 API 的使用情况和响应能力。 API 不是新的，多年来我们一直在发布与之交互的软件。它也相当大(数以千计的公共(public)方法)。我们的 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

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

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

这似乎是 Endpoints 团队恕我直言的疏忽，因为在正文中使用一组对象非常适合 OpenApi 规范，并且可以与 http://editor.swagger.io/ 等工具一起使用。

编辑:我还应该补充一点，仅使用原始数组作为请求主体或响应主体通常是不好的做法，因为如果在未来，比如计数或分页信息。
如果这是一个现有的 API，而您只是在记录现有的契约(Contract)，那么这个解决方案可以完成工作，但如果您正在设计一个新的 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