OpenAPI 3：如何在PATCH请求体中要求一个或多个属性？

Question

我有一个用户资源：

我想定义一个补丁，这样客户端就可以更新image、bio或两者。

有效的请求主体示例如下：

{
  "image": "filename.jpg",
  "bio": "My biography"
}

如果image属性单独发送，则现有的bio属性将在服务器上保持不变，并且只会更新图像。如果两者都发送（如上所述），两者都将更改。

简而言之：

>

不允许使用空的请求正文。

{"image"："new.jpg"}，{"bio"："new bio"or{"image"："new.jpg"，"bio"："new bio"是允许的。

这就是我目前所拥有的。我正在使用带有两个独立类型的anyOf对象：object。我曾使用virtserver在Swagger hub上尝试过这一点，但虚拟服务器似乎总是返回200 OK并返回示例数据，无论传递了什么，所以我没有办法知道。

我的定义符合我的意图吗？如果没有，最佳做法是什么？

openapi: 3.0.0
    ...
    
    patch:
      summary: update a user
      parameters:
        - in: path
          name: uid
          description: user id
          schema:
            type: string
          required: true
      requestBody:
        description: Update a user's profile
        content:
          application/json:
            schema:
              type: object
              anyOf:
                - type: object
                  properties:
                    image:
                      type: string
                - type: object
                  properties:
                    bio:
                      type: string
              additionalProperties: false
        required: true
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Answer 1

您可以使用minProperties:1：

      requestBody:
        description: Update a user's profile
        content:
          application/json:
            schema:
              type: object
              properties:
                image:
                  type: string
                bio:
                  type: string
              minProperties: 1   # <-----------
              additionalProperties: false

或所需的任何一项：

              type: object
              properties:
                image:
                  type: string
                bio:
                  type: string
              anyOf:   # <-----------
                - required: [image]
                - required: [bio]
              additionalProperties: false

您的原始示例定义了一个空对象{}，因为：

1. 如果未定义“必需”或“最小属性”，则所有属性都是可选的

至于：

我曾使用VirtServer在SwaggerHub上尝试过这一点，但虚拟服务器似乎总是返回200 OK，并返回示例数据，不管传递了什么。

这是因为SwaggerHub模拟不会验证输入，并且始终返回基于响应模式的静态响应。

从SwaggerHub留档：

请注意，mock不支持业务逻辑，即它不能根据输入发送特定响应。

...

模拟根据其响应和规范中定义的响应媒体类型为每个API操作生成静态响应。

如果一个操作有多个响应代码，则模拟返回具有最低状态代码的响应。例如，如果操作具有响应201、202和400，则模拟返回201响应。