cancel
Showing results for 
Search instead for 
Did you mean: 

How to give description to common Request and Response body properties

Highlighted
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 Technical Writer
________________________

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!
Highlighted
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

Highlighted
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 Technical Writer
________________________

 Join SmartBear Connect next April in Boston to meet with software development, API and testing experts from around the world! Get your ticket today!