OpenAPI 3中嵌套引用schema如何适配GET与POST的字段差异要求

完全可以仅调整Report POST接口的定义实现需求，不需要拆分整个Report的顶层schema，现有适配GET接口的User、Report schema可以完全保留不动，互不干扰。

为什么直接复用现有schema会出问题 #

• 现有User schema里的id被标记为readOnly: true，按照OpenAPI 3规范，readOnly字段仅允许出现在响应中、禁止作为请求输入，直接复用的话校验器会直接拦截你POST请求里传入的user.id
• 现有User schema没有对name字段做入参限制，无法满足你只接受用户id做关联的需求

推荐实现方案 #

方案1：定义可复用的关联引用schema（通用场景首选） #

你可以在components.schemas里新增两个专用schema，完全不改动原有适配GET响应的定义：

1. 新增UserRef schema，专门用于所有关联已有用户的请求场景（比如创建Report、创建其他关联用户的资源都可以复用）：

"UserRef": {
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    }
  },
  // 强制必须传id，且不允许传入name等其他任何字段
  "required": ["id"],
  "additionalProperties": false
}

2. 新增ReportCreateRequest schema，专门作为Report POST接口的请求体：

"ReportCreateRequest": {
  "type": "object",
  "properties": {
    "user": {
      "$ref": "#/components/schemas/UserRef"
    }
  },
  "required": ["user"],
  "additionalProperties": false
}

3. 最后修改Report POST接口的定义，把请求体的schema引用改为ReportCreateRequest即可。原有GET接口继续使用原来的Report schema当响应，完全不受影响。

方案2：直接内嵌请求结构（适合无复用需求的小场景） #

如果这个关联用户的场景只有Report POST用到，不想多定义两个顶层schema，也可以直接在POST接口的请求体里内嵌user结构：

# OpenAPI YAML格式示例，JSON格式逻辑一致
paths:
  /reports:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                  required: ["id"]
                  additionalProperties: false
              required: ["user"]

关于是否需要拆分整个Report schema的说明 #

不需要把原有Report拆成ReportGet、ReportPost两个独立的顶层schema。你只需要把请求体和响应分开定义即可，这是OpenAPI生态里的常规设计：通用的资源响应schema可以复用到所有GET、列表接口的响应中，而创建、更新类的请求体用单独的专用schema，避免不同场景的字段约束互相干扰。

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