使用 $ref 时忽略 Swagger 模式属性 - 为什么？

Question

我正在尝试为一个时间间隔构建一个 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 “描述”，而只显示原始时间“描述”。 这让我觉得我没有正确地做到这一点。

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

Answer 1

TL；DR：在 OpenAPI 3.1 中（在一定程度上）支持$ref兄弟姐妹。 在以前的 OpenAPI 版本中， $ref旁边的任何关键字都会被忽略。

开放API 3.1

迁移到 OpenAPI 3.1 后，您的定义将按预期工作。 这个新版本与 JSON Schema 2020-12 完全兼容，它允许在 schemas中使用$ref兄弟姐妹。

openapi: 3.1.0
...

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

    TimeInterval:
      type: object
      properties:
        lowerBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Lower bound on the time interval.
          default: "00:00"
        upperBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Upper bound on the time interval.
          default: "24:00"  

在模式之外- 例如，在响应或参数中 - $refs 仅允许同级summary和description关键字。 这些 $ref 旁边的任何其他关键字都将被忽略。

# openapi: 3.1.0

# This is supported
parameters:
  - $ref: '#/components/parameters/id'
    description: Entity ID

# This is NOT supported
parameters:
  - $ref: '#/components/parameters/id'
    required: true

以下是一些关于非模式 $ref 兄弟姐妹的 OpenAPI 功能请求，您可以跟踪/投票：

• 允许使用 $ref 覆盖引用定义的兄弟元素
• 允许需要作为 $ref 的兄弟（如摘要/描述）
• 扩展/覆盖参数的属性

OpenAPI 2.0 和 3.0.x

在这些版本中， $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"