使用$ ref时忽略Swagger架构属性 - 为什么?

时间:2015-11-10 12:14:42

标签: swagger swagger-2.0

我试图在一段时间间隔内构建一个Swagger模型,使用一个简单的字符串来存储时间(我知道还有datetime):

definitions:
  Time:
    type: string
    description: Time in 24 hour format "hh:mm".
  TimeInterval:
    type: object
    properties:
      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"
      upperBound:
        $ref: "#/definitions/Time"
        description: Upper bound on the time interval.
        default: "24:00"        

由于某种原因,生成的HTML不显示lowerBound和upperBound"描述",而只显示原始时间"描述"。这让我觉得我没有正确地做到这一点。

所以问题是如果使用模型作为一种类型实际上可以像我试图那样完成。

1 个答案:

答案 0 :(得分:3)

$ref通过将其自身和所有兄弟元素替换为它指向的定义来工作。这就是为什么

      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

变为

      lowerBound:
        type: string
        description: Time in 24 hour format "hh:mm".


可能的解决方法是将$ref包装到allOf中 - 这可用于将属性“添加”到$ref但不覆盖现有属性。

      lowerBound:
        allOf:
          - $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

另一种方法是使用内联定义替换$ref

definitions:
  TimeInterval:
    type: object
    properties:
      lowerBound:
        type: string  # <------
        description: Lower bound on the time interval, using 24 hour format "hh:mm".
        default: "00:00"
      upperBound:
        type: string  # <------
        description: Upper bound on the time interval, using 24 hour format "hh:mm".
        default: "24:00"


$ref的可用性正在OpenAPI规范存储库herehere中进行讨论,因此可能会在以后的某个版本中进行改进。