Nested schemas do not show description in swagger-ui

[Kadams64]

• OS: macOS 10.14
• Browser: Safari
• Version: 12.0
• Method of installation: Github download
• Swagger-UI version: 3.20.5
• Swagger/OpenAPI version: Swagger 2.0

The following snippet of Swagger JSON from my API includes a description for a nested property:

"reasonForDeletion":{"description":"The reason for deletion. VocabularyDomain=SubjectMgmtAllergyDeletionReason.","$ref":"#/definitions/CodedConceptReference"}}

The Swagger-ui output, however, does not display the nested entity description i.e.: it looks like this:

Steps to reproduce the behavior:

1. Use Swagger-UI to explore an API with a nested property having a description
2. Expand the nested property
3. Observe a lack of the 'description' text

Expected behaviour:
Descriptions of nested properties should appear immediately adjacent to the described property; the nested entity descriptions should then follow

Additional context or thoughts

• this problem has existed in every version of Swagger-UI going back well over a year. It has been reported several times, and described as 'fixed' several times as well

[hkosova]

Any sibling keywords alongside $refs are ignored, this is how $refs work. To combine a $ref with other properties, you need to wrap the $ref into allOf:

"reasonForDeletion": {
  "description":"The reason for deletion. VocabularyDomain=SubjectMgmtAllergyDeletionReason.",
  "allOf": {
    "$ref": "#/definitions/CodedConceptReference"
  }
}

[Kadams64]

Fair enough: that's not what I was told when I posted previously in an existing issue that was closed- I was told to re-open the issue.

But now I'm wondering, how do I represent this in terms of Swagger-annotated Java?

For example, using the Java code that produces the above Swagger JSON as an example:

@ApiModelProperty(value = "The reason for deletion. VocabularyDomain=SubjectMgmtAllergyDeletionReason.", required = true)
    public CodedConceptReference getReasonForDeletion()
    {
        return reasonForDeletion;
    }

And the referenced CodedConceptReference object is annotated as:

@ApiModel(description = "The coded concept reference resource.")
public class CodedConceptReference extends ResourceCommon
{
 ...


    @ApiModelProperty(value = "The code set OID.", example = "2.16.840.1.113883.5.1", required = false)
    public String getCodeSetOID()
    {
... etc

Where/how do I indicate that the referenced CodedConceptReference is to be given the 'allOf' treatment? To be clear, the outcome I expect/want is that:

• the @ApiModelProperty value text for reasonForDeletion is displayed in Swagger-UI followed by the referenced entity description for a CodedConceptReference entity

[raderio]

@Kadams64 have you found a solution?

[Kadams64]

No, I haven't. I've tried new releases of Swagger-UI as they have come out, but none (at least as of whatever was current about a week ago) have solved the problem.

I expect that the Swagger-UI developers don't feel this is a real issue. Personally, it is very real: referenced / nested schemas are used a lot in our API. One entity used in multiple places with different descriptions seems like it would be a pretty common use case; but either it isn't, or the contributors don't care.

[gavinBurtonStoreFeeder]

I need this also. My use case is that I have a standard "Address" schema, which is used in multiple places - for example, some schemas have a billing address and shipping address.

I suppose people can guess from the name, but that means I can't add any notes in addition (such as, this field is optional if you send the flag BillingEqualsShipping = true)

What is the driving reason behind the decision NOT to carry over property documentation if the type is an existing schema? The OpenApi spec clearly supports this.

[owengalenjones]

Likewise affected by this issue.