如何将两个OpenAPI/Swagger Schema合并为单个平铺对象Schema

你之前的写法存在两处错误：

1. 不应该将Schema的$ref放在properties字段下，properties是用于定义单个对象属性的字段，放入完整Schema引用会被识别为你要定义两个属性，每个属性的类型对应引用的Schema，自然会生成嵌套结构。
2. allOf关键字需要作为目标Schema的根级字段使用，而不是放在properties内部。

正确实现方式 #

使用allOf的正确写法如下（OpenAPI 3.x 版本通用）：

ResultantSchema:
  allOf:
    - $ref: '#/components/schemas/SchemaA'
    - $ref: '#/components/schemas/SchemaB'

这个写法的语义是：符合ResultantSchema的实例必须同时满足SchemaA和SchemaB的所有约束，两个Schema的属性会自动平铺合并，最终生成的结构就是你需要的包含所有属性的单个对象。

如果需要在合并的基础上额外新增属性，可以按如下写法扩展：

ResultantSchema:
  allOf:
    - $ref: '#/components/schemas/SchemaA'
    - $ref: '#/components/schemas/SchemaB'
  type: object
  properties:
    # 此处可添加合并之外的自定义属性
    additional_prop:
      type: integer

注意事项 #

• 如果SchemaA和SchemaB存在同名属性，合并后该属性需要同时满足两个Schema对该属性的约束，若约束冲突（比如一个定义为字符串、一个定义为数字），则合并后的Schema为无效约束。
• 请确认$ref的路径和你实际OpenAPI文件中Schema的存储位置匹配，示例中路径默认适配OpenAPI 3.x规范下Schema存放在components/schemas节点下的通用写法；如果使用的是Swagger 2.0规范，调整$ref路径为#/definitions/你的Schema名即可。

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