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

Question

我有一个 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"。

这就是我目前所拥有的。我正在使用带有两个单独 type: object 的 anyOf 对象。我已经使用 virtserver 在 Swagger hub 上尝试过这个，但是虚拟服务器似乎总是 return 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

或anyOf + required:

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

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

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

至于：

I've tried this with SwaggerHub using the VirtServer, but the virtual server always seems to return 200 OK and passes back the example data regardless of whatever is passed.

这是因为 SwaggerHub 模拟不验证输入并且总是 return 基于响应 schema 的静态响应。

来自 SwaggerHub documentation:

Note that the mock does not support business logic, that is, it cannot send specific responses based on the input.

...

The mock generates static responses for each API operation based on its responses and the response media types defined in the spec.

If an operation has multiple response codes, the mock returns the response with the lowest status code. For example, if an operation has responses 201, 202 and 400, the mock returns the 201 response.

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

OpenAPI 3: How to require one or more properties in PATCH requestBody?

rest

swagger

openapi