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(不确定这可能是由于最近更新到 3.0.2 版本的 Swagger UI)

      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"

如果这个答案不是您要找的，请重述问题。我们需要知道你想要完成什么。