如何在OpenAPI中规范定义JSON Merge Patch接口文档？

你基于 springdoc-openapi 实现了遵循 OpenAPI 规范的 REST API 自动文档，现在需要为接口增加 PATCH 类型的部分更新能力，当前接口定义如下：

/customers/{id}:
  patch:
    tags:
      - Customers
    summary: Updates an existing user
    description: Updates an existing user
    operationId: partialUpdateMergePatchCustomer
    parameters:
      - name: id
        in: path
        description: The numeric ID of the customer
        required: true
        schema:
          type: integer
          format: int64
    requestBody:
      content:
        application/merge-patch+json:
          schema:
            type: object
      required: true

查阅OpenAPI官方规范未找到JSON Merge Patch、JSON Patch相关的明确配置说明，目前有两个待解决问题：

• 当前请求体定义未关联待修补的资源类型，其余API（尤其是SwaggerUI展示层）都配置了完整的schema引用，需要明确PATCH接口指定对应资源schema的方法
• 资源中包含只读字段、部分字段存在修改约束，需要比自然语言描述更规范的字段约束标注方式

解决方案 #

1. 为Merge Patch请求体关联对应资源Schema #

OpenAPI 3.x 原生支持application/merge-patch+json媒体类型，不需要引入额外扩展，直接通过$ref引用对应资源的全量Schema即可，不需要单独为PATCH请求新建独立Schema。
调整后的请求体配置示例：

requestBody:
  content:
    application/merge-patch+json:
      schema:
        $ref: '#/components/schemas/Customer'
  required: true

如果是springdoc-openapi的Java编码场景，直接在PATCH接口方法参数上添加对应注解即可自动生成上述配置：

@io.swagger.v3.oas.annotations.parameters.RequestBody(
  content = @Content(
    mediaType = "application/merge-patch+json",
    schema = @Schema(implementation = Customer.class)
  )
)

配置完成后SwaggerUI会自动识别该媒体类型，渲染出和POST/PUT接口一致的字段表单与请求示例，不需要额外做前端适配。

注意：不要像当前配置一样把Schema设为空的type: object，否则SwaggerUI无法展示可编辑字段列表，也无法生成正确的请求示例。

2. 只读字段与修改约束的规范标注 #

不需要在字段描述中堆砌自然语言说明，直接使用OpenAPI Schema内置关键字和通用扩展属性标注即可，SwaggerUI、SDK生成工具等生态组件会自动识别这些标记做对应提示：

• 永久只读字段：给系统生成、不允许任何写入操作修改的字段添加readOnly: true属性。标注后SwaggerUI会在字段旁展示明确的只读标识，同时自动提示该字段不需要在请求体中传入，即使传入服务端也会忽略。
  Schema配置示例：

  components:
    schemas:
      Customer:
        type: object
        properties:
          id:
            type: integer
            format: int64
            readOnly: true # 主键为系统生成，只读不可修改
          createTime:
            type: string
            format: date-time
            readOnly: true # 创建时间为系统自动写入，只读
          username:
            type: string
          email:
            type: string
  

• 通用字段约束：直接使用OpenAPI内置的校验关键字标注即可，常用的包括：
  • writeOnly: true：标记仅可写入、不会在响应中返回的字段（比如密码、验证码类字段）
  • minLength/maxLength：字符串类型的长度上下限约束
  • minimum/maximum：数值类型的取值范围约束
  • pattern：字段值需要匹配的正则格式约束
• PATCH场景专属不可修改字段：针对创建时可传入、但后续更新不允许修改的字段（比如用户注册时设置的用户名），可以添加通用扩展属性x-patch-read-only: true，springdoc-openapi以及绝大多数OpenAPI生态工具都支持识别该标记，会在PATCH接口的文档中单独标注该字段不可修改，同时不会影响POST创建接口的字段可用状态。

如果是springdoc-openapi基于Java代码生成文档，直接在实体类字段上添加对应注解即可自动生成上述配置：

• 永久只读字段添加@Schema(readOnly = true)注解
• 通用字段约束直接使用Jakarta Validation（原JSR-380）注解即可，比如@Size、@Min、@Max、@Pattern，springdoc会自动把这些校验规则映射为OpenAPI Schema对应的约束关键字
• PATCH场景不可修改的字段，添加@Schema(extensions = @Extension(name = "x-patch-read-only", properties = @ExtensionProperty(name = "value", value = "true", parseValue = true)))注解

内容的提问来源于stack exchange，提问作者user1049746