在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。