$ref and description/title

[vsr]

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

?

[vsr]

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

myProperty:

  description: My description

  allOf:

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

[hugomario · Accepted solution]

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 

[vsr]

Thanks!

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

[stokestack]

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.