OpenAPI 3：如何在 PATCH requestBody 中要求一个或多个属性？答案

【问题标题】：OpenAPI 3: How to require one or more properties in PATCH requestBody?OpenAPI 3：如何在 PATCH requestBody 中要求一个或多个属性？
【发布时间】：2022-01-27 22:51:34
【问题描述】：

我有一个User 资源：

我想定义一个 PATCH /users/{uid} 以便客户端可以更新image、bio 或两者。

一个有效的请求正文示例是：

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

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

简而言之：

不允许使用空的请求正文 {}。
{"image": "new.jpg"}、{"bio": "new bio" 或 {"image": "new.jpg", "bio": "new bio" 是允许的。

这是我目前所拥有的。我正在使用 anyOf 对象，其中包含两个单独的 type: objects。我已经在使用 virtserver 的 Swagger 集线器上进行了尝试，但虚拟服务器似乎总是返回 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'

【问题讨论】：

标签： rest swagger openapi

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

或anyOf + required:

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

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

未定义required 或minProperties，all properties are optional。
更重要的是，additionalProperties: false 只知道直接在其旁边定义的properties 并具有no visibility into subschemas。因此，在此示例中，它不允许所有属性。

至于：

我已经在 SwaggerHub 上使用 VirtServer 进行了尝试，但虚拟服务器似乎总是返回 200 OK 并传回示例数据，无论传递什么。

这是因为 SwaggerHub 模拟不会验证输入，并且始终根据响应 schema 返回静态响应。

来自SwaggerHub documentation：

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

...

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

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

【讨论】：