How to reference the id of another model definition in Swagger

Question

Suppose I have a User model and a UserType. I would like to add a link to the UserType-ID in the User model. The swagger documentation only shows how to reference another (whole) model, and not just one of its properties.

So I was wondering that you can even refer only to a property of another model definition.

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

Or is this impossible at all, and it must always be fair:

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

Answer 1

In Swagger 2.0, schematic objects do not necessarily describe models (as opposed to the model object in previous versions). For example, if you look at the "body" parameters, you will see that you need to define a scheme as a type, but this scheme can also represent primitives and arrays.

In the question above (and comments), I would suggest using the following structure:

 "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 is now filmed, and if the time comes, and you want to change its definition, you can change it in one place. Of course, you can add additional "description" to the fields and models to better document the goal.