rest - Swagger 和 JSON 补丁

Question

我的数据库中有以下对象结构

{
    partnerName: '24 Fitness',
    supportedProducts: [
        'FitBit',
        'Protein Powder'
    ]
},

其中键值 支持产品 可以从客户端修改。

我正在使用 swagger 文档构建 PATCH API 方法来支持上述功能。但是我不确定补丁对象的定义，因为文档没有提供构建补丁的详细示例。

我的当前定义在执行时最终出错，如下所示

 "patch":{
    "description":"Update supported products for a partner",
    "operationId":"Update supported products",
    "parameters":[
      {
        "name": "partnerName",
        "in": "path",
        "required": true,
        "type": "string"
      },
      {
        "name": "supportedProducts",
        "in": "body",
        "required": true,
        "schema":{
          "$ref":"#/definitions/PatchRequest"
        }
      }
    ],
    "responses":{
      "200":{
        "description": "product updated"
      },
      "404":{
        "description": "Not Found"
      }
    }

  "definitions": {
    "PatchRequest":{
      "type": "object",
      "required":[
        "partnerName",
        "supportedProducts"
      ],
      "properties":{
        "partnerName":{"type": "string"},
        "supportedProducts":{
          "type": "array",
          "items":{"type": "string"}
        }
      }

    }
  }

Answer 1

对于这个简单的案例，我会使用 JSON Patch对象来描述对目标进行的操作。
这是一个 example JSON 补丁 Swagger API。

paths:
  /users/{GUID}:
    patch:
      summary: Update a user
      parameters:
        - name: GUID
          in: path
          required: true
          type: string
          format: GUID
          description: The GUID of a specific user 
        - name: JsonPatch
          in: body
          required: true
          schema:
            $ref: "#/definitions/PatchRequest"
      responses:
        '200':
          description: Successful response
          schema:
            $ref: "#/definitions/User"
definitions:
  PatchRequest:
    type: array
    items:
      $ref: "#/definitions/PatchDocument"
  PatchDocument: 
    description: A JSONPatch document as defined by RFC 6902 
    required:
     - "op"
     - "path"
    properties: 
     op: 
      type: string 
      description: The operation to be performed 
      enum:
       - "add"
       - "remove"
       - "replace"
       - "move"
       - "copy"
       - "test"
     path: 
      type: string 
      description: A JSON-Pointer 
     value: 
      type: object 
      description: The value to be used within the operations.
     from: 
      type: string 
      description: A string containing a JSON Pointer value.