谷歌云端点正文数组

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

我在Endpoints遇到了完全相同的问题，在该问题上似乎并不认为传递对象数组作为body参数是有效的。我只是通过使用通用对象和适当的描述来解决此问题。该描述不会以编程方式修复任何问题，但是使用通用对象可以使Endpoints正常工作，并且该描述可向API使用者提供所需信息。

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

这似乎是端点团队恕我直言的疏忽，因为使用体内的对象数组适合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