So verweisen Sie auf eine ID einer anderen Modelldefinition in Swagger

Question

Nehmen wir an, ich habe ein Benutzer- und ein UserType-Modell. Ich möchte einen Verweis auf die UserType-ID im Benutzermodell hinzufügen. Die Swagger-Dokumentation zeigt nur, wie man sich auf ein anderes (ganzes) Modell bezieht, nicht nur auf eine seiner Eigenschaften.

Also habe ich mich gefragt, ob es überhaupt möglich ist, nur auf eine Eigenschaft einer anderen Modelldefinition zu verweisen.

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

Oder ist das gar nicht möglich und es sollte immer nur sein:

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

Answer 1

In Swagger 2.0 Schemaobjekte nicht notwendig Modelle beschreiben (im Gegensatz zum Modell Objekt in früheren Versionen). Wenn Sie sich beispielsweise "body" -Parameter ansehen, müssen Sie ein Schema als Typ definieren, aber dieses Schema kann auch Primitive und Arrays darstellen.

Für die oben gestellte Frage (und Kommentare), ich würde vorschlagen, die folgende Struktur verwendet:

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

Die TypeId jetzt externalisiert, und sollte die Zeit kommen, und Sie ihre Definition ändern möchten, können Sie ändere es an einem Ort. Natürlich können Sie den Feldern und Modellen zusätzliche "description" hinzufügen, um den Zweck der.