Missing description on $ref

[RobertPaasche]

Q&A (please complete the following information)

• OS: macOS, Windows, Linux
• Browser: Any
• Version: any
• Swagger-UI version: 3.18.1]
• Swagger/OpenAPI version: Swagger 2.0

Content & configuration

Example Swagger/OpenAPI definition:

"PersonDto": {
			"type": "object",
			"properties": {
				"salutation": {
					"description": "The selected salutation with all available translations.",
					"$ref": "#/definitions/LabelSetDto"
				},
				"position": {
					"description": "The selected position with all available translations.",
					"$ref": "#/definitions/LabelSetDto"
				}
			},
			"description": "Person data for a specific charset."
		}

  PersonDto:
    type: "object"
    properties:
      salutation:
        description: "The selected salutation with all available translations."
        $ref: "#/definitions/LabelSetDto"
      position:
        description: "The selected position with all available translations.",
        $ref: "#/definitions/LabelSetDto"

Describe the bug you're encountering

The description provided for salutation is not rendered at the response body.

[hkosova]

Any keywords alongside $ref are ignored - that's how $ref works.

You need to wrap the $ref into allOf in order for the description to have effect:

  PersonDto:
    type: "object"
    properties:
      salutation:
        description: "The selected salutation with all available translations."
        allOf:
          - $ref: "#/definitions/LabelSetDto"
      position:
        description: "The selected position with all available translations.",
        allOf:
          - $ref: "#/definitions/LabelSetDto"

[RobertPaasche]

Ok I had to create empty sub classes like the samples of swagger-api/swagger-core#1549 .