cancel
Showing results for 
Search instead for 
Did you mean: 

$ref and description/title

SOLVED
vsr
New Contributor

$ref and description/title

The page https://swagger.io/docs/specification/using-ref/ says that when I am using $ref in an OpenAPI spec all sibling properties are ignored. It is not quite clear if there is a way to workaround this issue. Can I use for example


myProperty:

  allOf:

    - $ref: '#/components/schemas/MyType'

    - description: My description

 

?

1 ACCEPTED SOLUTION

Accepted Solutions
hugomario
Staff

Re: $ref and description/title

Hello @vsr 

 

that depends of what open api version are you working, for openapi version 3.0.x the reference object does not have any other fields than $ref, you can check that here . 

 

But for open api 3.1.x you can certainly add a description to the reference object as it's described here 

 

View solution in original post

4 REPLIES 4
vsr
New Contributor

Re: $ref and description/title

... or even this (which I found on Internet):

 

myProperty:

  description: My description

  allOf:

    - $ref: '#/components/schemas/MyType'

 

hugomario
Staff

Re: $ref and description/title

Hello @vsr 

 

that depends of what open api version are you working, for openapi version 3.0.x the reference object does not have any other fields than $ref, you can check that here . 

 

But for open api 3.1.x you can certainly add a description to the reference object as it's described here 

 

View solution in original post

vsr
New Contributor

Re: $ref and description/title

Thanks!

 

As I understand, version 3.1 is not released yet? Do you know anything about planned release date?

stokestack
Occasional Contributor

Re: $ref and description/title

Thanks. It's good to know that this perplexing and crippling limitation has been addressed, at least for 3.1. Let's hope it's released soon.

New Here?
Join us and watch the welcome video: