昂首阔步：用ref添加描述

Question

我想向引用其定义的对象属性添加描述。像这样：

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

但是编辑器警告说description属性将被跳过：

Extra JSON Reference properties will be ignored: description

我发现了一种不太优雅的解决方法，该方法适用于编辑器，但不适用于Swagger UI（不确定这可能是由于Swagger UI的3.0.2版本最近进行了更新）

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

您如何在Swaggers规范中做到这一点？

谢谢您的帮助！

Answer 1

如果您将任何内容添加到同一级别，$ref它将被忽略。

json $ref 定义https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3

正确的方法是在引用的对象中提供描述。