OpenAPI中oneOf引用字符串类型组件是否为最优定义方式？

你的当前写法不是最优方案，甚至存在实际校验无效的问题——因为type1Id和type2Id都是无任何约束的字符串，OpenAPI校验工具没办法区分一个字符串到底属于哪一种，oneOf在这里只是形式上满足了语法，但达不到“二选一”的实际校验效果。

优化方案分两种场景： #

场景1：两个ID有格式差异（比如不同的编码规则）

如果type1Id和type2Id有可识别的格式区别（比如type1是T1-xxxx，type2是T2-xxxx），可以直接给每个类型加上正则约束，不用单独拆组件，写法更简洁：

"domainId": {
  "oneOf": [
    {
      "type": "string",
      "pattern": "^T1-\\w+$",
      "description": "type1类型的ID"
    },
    {
      "type": "string",
      "pattern": "^T2-\\w+$",
      "description": "type2类型的ID"
    }
  ]
}

如果需要复用这两个ID定义，也可以给组件加pattern后再引用，这样既复用又能实现有效校验。

场景2：两个ID格式完全一致，仅语义不同

这种情况下，单纯用字符串无法区分，必须把每个ID包装成带标识字段的对象，结合discriminator来实现二选一的校验：

"domainId": {
  "oneOf": [
    { "$ref": "#/components/schemas/Type1IdObj" },
    { "$ref": "#/components/schemas/Type2IdObj" }
  ],
  "discriminator": {
    "propertyName": "type",
    "mapping": {
      "type1": "#/components/schemas/Type1IdObj",
      "type2": "#/components/schemas/Type2IdObj"
    }
  }
},
"components": {
  "schemas": {
    "Type1IdObj": {
      "type": "object",
      "required": ["type", "id"],
      "properties": {
        "type": { "type": "string", "enum": ["type1"] },
        "id": { "type": "string" }
      }
    },
    "Type2IdObj": {
      "type": "object",
      "required": ["type", "id"],
      "properties": {
        "type": { "type": "string", "enum": ["type2"] },
        "id": { "type": "string" }
      }
    }
  }
}

这样客户端必须传递带type标识的对象，校验工具能通过type字段准确判断是否符合oneOf的要求。

补充说明 #

如果你的需求只是在文档层面说明“二选一”，不需要强校验，当前写法勉强能用，但团队协作或自动化校验时会有歧义，建议还是按上面的场景优化。

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