Attributes consisting in resource ids : how to link it with these resources ?

[Alexandre Estela]

Hi all,

First, thank you for the great work provided by the Swagger community. I am heavily relying on it to provide API-design support to my customers, as its tooling is rather complete and user-friendly.

I am currently helping a customer to represent a very complex API through a Swagger specification document. I managed to do a lot with existing 2.0 features, including polymorphism/inheritance and resource composition (using $ref). What I am missing though, is an "official" way of indicating that an attribute/parameter actually represents a resource id. This is useful in order to generate diagrams showing resource relationships, for example.

Assume we have a resource such as :

"cat": {

  "foodPreferences": {

     "favoriteDrink": "milk",

     "favoriteFood": "fish"

  },

  "ownerId": "110e8400-e29b-11d4-a716-446655440000"

}

In this case, attribute "foodPreferences" is an embedded resource of type "FoodPreferences". Attribute "ownerId" is the id of another resource, not embedded here, of type "Owner".

To indicate the link between the "ownerId" attribute and the "Owner" resource, we use the following Swagger-based specification :

"definitions": {

  "Dog": {

    "allOf": [

      {

        "type": "object",

        "properties": {

          "foodPreferences": {

            "description": "Embedded resource",

            "$ref": "#/definitions/FoodPreferences"

          },

          "ownerId": {

            "description": "Number representing an id (reference) to another resource",

            "type": "number",

            "x-identifier-for-schema-ref": "#/definitions/Owner"

          }

     }

}

As you can see we defined a specific "x-identifier-for-schema-ref" specification field (in red) to indicate this particular link.

We also use this specification field to support this use case in path parameters :

"post": {

"parameters": [{

"in": "path",

"name": "ownerId",

"type": "string",

"x-identifier-for-schema-ref": "#/definitions/Owner",

"required": true

}]

}

Any thoughts about such requirement ? Do you have suggestions regarding other ways of dealing with this use case ?

Alexandre

[tony tam]

Hi, good question.  There is currently no mechanism to do this in the spec, but you might consider contributing your ideas to that repo.  We're looking for input on where it's lacking, and how it can be improved!

The way you're using the extensions is exactly what we hoped for, though, so thank you for sharing that solution.