cancel
Showing results for 
Search instead for 
Did you mean: 

How to give description to common Request and Response body properties

New Contributor

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 3
Moderator

Re: How to give description to common Request and Response body properties

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

 


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
New Contributor

Re: How to give description to common Request and Response body properties

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

Moderator

Re: How to give description to common Request and Response body properties

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


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors