Swagger: Add description with ref

问题

I want to add a description to an object property that his definition is referenced. Something like that:

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            $ref: "#/definitions/PhoneNumber"

But the editor warns that the description property will be skipped:

Extra JSON Reference properties will be ignored: description

I have found a less elegant workaround that works for the editor, but not for the Swagger UI (not sure that is may due to the recent update to 3.0.2 version of the Swagger UI)

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            allOf:
            - $ref: "#/definitions/PhoneNumber"

How do you do it in your Swaggers specification?

Thanks for the help!

回答1:

If you add anything to the same level of $ref it will be ignored .

json $ref definition https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

correct way is to provide the description in the referenced object.

回答2:

You could simply move the description property to the definition of PhoneNumber. Your original post does not show how you have defined PhoneNumber, but this snippet validates without warnings:

definitions:
  phoneNumber:
    type: string
    description: Phone number of the card holder

  newCreditCard:
    type: object
    properties:
      billingPhone:
        $ref: "#/definitions/phoneNumber"

If this answer is not what you are looking for, please restate the question. We need to know what you are trying to accomplish.

来源：https://stackoverflow.com/questions/43003348/swagger-add-description-with-ref