1

I have an issue writing my swagger file. When I describe a parameter the description is overloaded by the description of the $ref of this same parameter (see the example bellow).

a-body:
    description: The body
    type: object
    properties:
      my_param:
        description: Full description 
        $ref: '#/definitions/reference'

definitions:
    reference:
        type: object
        required: [req]
        description: an http reference
        properties:
          req:
            type: string

The result: the description is overloaded

Can somebody help me get through this please ?

VisualPi
  • 91
  • 1
  • 4

1 Answers1

1

$ref overwrites all of its sibling properties - it's how $ref works. You can try to work around this using something like:

my_param:
  description: Full description 
  allOf:
    - $ref: '#/definitions/reference'

This will work in Swagger Editor and Swagger UI.

There's also a feature request in the OpenAPI Specification repository to provide a better way to combine $ref with other properties.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • I'm using a buggy plugin on vs code so it's not working but I can't do otherwise ! Thanks for your help ! – VisualPi Nov 07 '17 at 11:00