Swagger：使用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

您只需将description属性移动到PhoneNumber的定义即可。您的原始帖子未显示您已定义PhoneNumber的方式，但此代码段会在没有警告的情况下进行验证：

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

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

如果您的答案不符合您的要求，请重新提出问题。我们需要知道你想要完成什么。

Answer 2

如果您向$ref的同一级别添加任何内容，则会被忽略。

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

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