Forum Discussion

vsr's avatar
vsr
New Contributor
5 years ago

$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

 

?

  • hugomario's avatar
    hugomario
    5 years ago

    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's avatar
    vsr
    New Contributor
    5 years ago

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

     

    myProperty:

      description: My description

      allOf:

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

     

    • hugomario's avatar
      hugomario
      Staff
      5 years ago

      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's avatar
        vsr
        New Contributor
        5 years ago

        Thanks!

         

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