Swagger 和 JSON 补丁答案

【问题标题】：Swagger and JSON PatchSwagger 和 JSON 补丁
【发布时间】：2017-07-09 23:29:42
【问题描述】：

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

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

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

我正在使用 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"}
        }
      }

    }
  }

【问题讨论】：

您的服务器期望什么请求 URL 和正文？
@Helen 请求 URL 是 /data/{partnerName} 并且正文应该期望 partnerName 和 supportedProducts 作为值。但在我的情况下，当我尝试配置上述 json 时，这会失败，在我可以运行服务器并发出请求之前
这是您的整个 JSON 定义还是只是其中的摘录？（询问是因为仅此代码不是有效的 JSON。）
@Helen 这只是其中的一部分，而不是整个 json，只是我用于补丁的部分

标签： rest swagger swagger-ui

【解决方案1】：

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

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.

【讨论】：

【解决方案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:
        ...

【讨论】：

您将如何强制执行补丁值的子组件类型？例如，假设您的路径是 /users/dj29_some_user_id_fn32ifn3/address 并且值中的对象是地址类型组件？

【解决方案3】：

由于 RFC 6902 很好地定义了 JSON Patch 格式，我认为指定 RFC 中定义的内容类型就足够了（至少对于 OpenAPI 3），因为似乎有必要定义架构或示例（至少在我的招摇编辑器中），还要指定类型：字符串和格式：JSON 补丁或格式：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

【讨论】：