在Swagger文档中结合定义

Question

我正在用Swagger文档记录API。我有几个共享一组通用属性的端点。我想使用$ ref引用该基本属性集，然后使用每个端点独有的附加属性扩展这些属性。我想象它会工作是这样的，但这是无效的：

"properties": { 
    "$ref": "#/definitions/baseProperties", 
    unique_thing": { 
     "type": "string" 
    }, 
    "another_unique_thing": { 
     "type": "string" 
    } 
} 

Answer 1

事实上，你在这里给出的例子是无效的，在同一对象的其他属性，因为$ref不能共存。 $ref是一个JSON参考，根据定义，将导致其他属性被忽略。

从你的问题，我假设你正在寻找基本组成（而不是继承）。这可以使用关键字allOf来实现。

所以，你所提供的例子，你有这样的事情：

{ 
    "baseProperties": { 
    "type": "object", 
    "properties": { 
     ... 
    } 
    }, 
    "complexModel": { 
    "allOf": [ 
     { 
     "$ref": "#/definitions/baseProperties" 
     }, 
     { 
     "type": "object", 
     "properties": { 
      "unique_thing": { 
      "type": "string" 
      }, 
      "another_unique_thing": { 
      "type": "string" 
      } 
     } 
     } 
    ] 
    } 
} 

您还可以检查出example in the spec。