Forum Discussion

HareeshKota's avatar
HareeshKota
New Contributor
5 years ago

How to give description to common Request and Response body properties

Hi,

 

I have few a request and response definitions which shares some properties. Instead of giving description to the same property/parameter in all the definitions, is there any way to describe them at one place and then refer them in the request or respone bodies?

 

In the attched file the parameters "clientKey" and "clientSecret" were repeated and the description to these params were given twice. Like this these parametes reapeats in multiple places and descrbing them everywhere is difficult. Hence is there anyway to descrbie them at one place and refer at the remaing.

3 Replies

Sort By
  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)
    5 years ago

    You can define a base schema with common properties and use allOf+$ref to "inherit" from that base schema.

     

    In your example, you can inherit the sessionOpenResponse schema from sessionCloseRequest as follows:

     

    "sessionOpenResponse": {
  "allOf": [
    {
      "$ref": "#/definitions/sessionCloseRequest"
    },
    {
      "type": "object",
      "properties": {
        "oauthToken": {
          "description": "This token is valid for 60 mins. and should be passed as 'Authorization: Bearer oauthToken' header when invoking the APIs",
          "example": "0efb61f4-3b06-3502-8987-c6e2e187244c",
          "type": "string"
        }
      }
    }
  ]
}

     

    • HareeshKota's avatar
      HareeshKota
      New Contributor
      5 years ago

      Thank You Helen Kosova for the response.

      That's helpful, but how to handle this when I have few more properties in "sessionCloseRequest" and i don't want all of them to be referred in to the "sessionOpenResponse" ? How to refere a few particular properties ?

       

      Regards,

      Hareesh

      • HKosova's avatar
        HKosova
        SmartBear Alumni (Retired)
        5 years ago

        Define a base schema with common properties and inherit both sessionCloseRequest and sessionOpenResponse from that base schema.