Swagger and JSON Patch

Question

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

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

在客户端可以修改键值supportedProducts。

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

我目前拥有的定义执行时出现错误，看起来如下：

 "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"}
        }
      }

    }
  }

- user8222014

---

你的服务器期望什么请求URL和请求体？ - Helen

@Helen 请求的URL是/data/{partnerName}，请求体应该包含partnerName和supportedProducts作为值。但在我的情况下，在我尝试配置上述JSON之前就失败了，甚至无法运行服务器并发出请求。 - user8222014

这是您的整个JSON定义还是其中的一部分？（问这个问题是因为仅凭这段代码不是有效的JSON。） - Helen

@Helen 这只是其中的一部分，不是整个 JSON，只是我用于 patch 的部分。 - user8222014

Answer 1

对于这个简单的情况，我会使用JSON Patch对象来描述要在目标上执行的操作。 下面是一个JSON Patch 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.

- intotecho

Answer 2

对于 OpenApi 3.0.x，.yaml 文件的结构已经发生了变化。一个有效的定义可能如下所示：

components:
  requestBodies:
    PatchBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchBody'

  schemas:
    PatchBody:
      type: array
      items:
        $ref: "#/components/schemas/PatchDocument"

    PatchDocument:
      type: object
      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.            

    patch:
      parameters:
        - $ref:  '#/components/parameters/objectId'
      requestBody:
        $ref: '#/components/requestBodies/PatchBody'
      responses:
        ...

- stacker

---

如果要强制执行补丁值的子组件类型，您会如何处理？ 例如，假设您的路径为 /users/dj29_some_user_id_fn32ifn3/address，而值中的对象是 Address 类型组件。 - AlleyOOP

Answer 3

由于RFC 6902已经很好地定义了JSON Patch格式，因此我认为（至少对于OpenAPI 3），指定RFC中定义的内容类型就足够了。而且由于在我的swagger编辑器中似乎需要定义模式或示例，因此还需要指定type: string和format: JSON Patch或format: RFC 6902。

重新定义已经在RFC中明确定义的格式是没有意义的。

例如：

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 
      requestBody:
        content:
          application/json-patch+json:
            schema:
              type: string
              format: RFC 6902

- na6cet