Sposób odwoływania się do identyfikatora innej definicji modelu w Swagger

Question

Załóżmy, że mam model User i UserType. Chciałbym dodać odniesienie do UserType-ID w modelu użytkownika. Dokumentacja typu "swagger" pokazuje jedynie jak odwoływać się do innego (całego) modelu, a nie tylko do jednej z jego właściwości.

Tak więc zastanawiałem się, czy możliwe jest odniesienie tylko do właściwości innej definicji modelu.

"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" 
      } 
     } 
    } 
} 

Albo jest to, że w ogóle nie jest możliwe i powinno być zawsze tylko:

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

Answer 1

W Swagger 2.0, Schemat Obiekty nie konieczne opisać modele (w przeciwieństwie do modelu obiektowego w poprzednich wersjach). Na przykład, jeśli spojrzysz na parametry "body", zobaczysz, że musisz zdefiniować Schemat jako typ, ale ten schemat może również reprezentować prymitywy i tablice.

Na powyższe pytanie (i komentarze), polecam stosując następującą strukturę:

"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 jest teraz externalized i powinien przyjść czas i chcesz zmienić swoją definicję, można zmień go w jednym miejscu. Oczywiście możesz dodać dodatkowe "description" do pól i modeli, aby lepiej udokumentować cel.