如何引用Swagger中另一個模型定義的ID

Question

假設我有一個User和一個UserType模型。我想在用戶模型中添加對UserType-ID的引用。 swagger文檔僅顯示如何引用另一個（整個）模型，而不僅僅涉及它的一個屬性。

所以我想知道它甚至有可能只引用另一個模型定義的屬性。

"definitions": { 
    "User": { 
     "required": [ 
      "username", 
      "typeId" 
     ], 
     "properties": { 
      "id": { 
       "type": "integer", 
       "format": "int32" 
      }, 
      "username": { 
       "type": "string" 
      }, 
      "typeId": { 
       "$ref": "UserType.id" // ==> this doesn't work! and without 
             // the ".id" part it would include all 
             // the properties of UserType 
      } 
     } 
    }, 
    "UserType": { 
     "required": [ 
      "name" 
     ], 
     "properties": { 
      "id": { 
       "type": "integer", 
       "format": "int32" 
      }, 
      "name": { 
       "type": "string" 
      } 
     } 
    } 
} 

或者是根本不可能的，它應該永遠只是：

"definitions": { 
    "User": { 
     ... 
     "properties": { 
      "typeId": { 
       "type": "integer", 
       "format": "int32" 
      } 
     } 
    }, 
    ... 
} 

Answer 1

在揚鞭2.0，方案對象沒有必要描述模型（不像在以前的版本中的模型對象）。例如，如果查看「body」參數，則會看到需要將Schema定義爲類型，但該模式也可以表示基元和數組。

對於上面的問題（和評論），我建議使用以下結構：

"defintions": { 
    "User": { 
    "required": [ 
     "username", 
     "typeId" 
    ], 
    "properties": { 
     "id": { 
     "type": "integer", 
     "format": "int32" 
     }, 
     "username": { 
     "type": "string" 
     }, 
     "typeId": { 
     "$ref": "#/definitions/TypeId" 
     } 
    } 
    }, 
    "UserType": { 
    "required": [ 
     "name" 
    ], 
    "properties": { 
     "id": { 
     "$ref": "#/definitions/TypeId" 
     }, 
     "name": { 
     "type": "string" 
     } 
    } 
    }, 
    "TypeId": { 
    "type": "integer", 
    "format": "int32" 
    } 
} 

的TYPEID現在外部化，並應時間來和你想改變它的定義，你可以在一個地方改變它。當然，您可能需要在字段和模型中添加額外的"description"以更好地記錄該目的。