使用 $ref 时忽略 Swagger 模式属性 - 为什么? [英] Swagger schema properties ignored when using $ref - why?

问题描述

我正在尝试建立一个时间间隔的Swagger模型，使用一个简单的字符串来存储时间(我知道还有datetime):

I'm trying to build a Swagger model for a time interval, using a simple string to store the time (I know that there is also 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 描述"，而只显示原始 Time 描述".这让我觉得我没有正确地做到这一点.

For some reason the generated HTML does not show the lowerBound and upperBound "description", but only the original Time "description". This makes me think I'm not doing this correctly.

所以问题是，使用模型作为类型实际上是否可以像我尝试的那样完成.

So the question is if using a model as a type can in fact be done as I'm trying to do.

推荐答案

TL;DR:OpenAPI 3.1 支持 $ref 同级.在以前的 OpenAPI 版本中，$ref 旁边的任何关键字都会被忽略.

TL;DR: $ref siblings are supported in OpenAPI 3.1. In previous OpenAPI versions, any keywords alongside $ref are ignored.

迁移到 OpenAPI 3.1 后，您的定义将按预期工作.这个新版本与 JSON Schema 2020-12 完全兼容，允许 $ref 同级在模式中.

Your definition will work as expected when migrated to OpenAPI 3.1. This new version is fully compatible with JSON Schema 2020-12, which allows $ref siblings in schemas.

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 旁边的任何其他关键字都将被忽略.

Outside of schemas - for example, in responses or parameters - $refs only allow sibling summary and description keywords. Any other keywords alongside these $refs will be ignored.

# 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

OpenAPI 2.0 和 3.0.x

在这些版本中，$ref 的工作原理是用它所指向的定义替换它自己和 它的所有兄弟元素.这就是为什么

OpenAPI 2.0 and 3.0.x

In these versions, $ref works by replacing itself and all of its sibling elements with the definition it is pointing at. That is why

      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 的属性，但不覆盖现有属性.

A possible workaround is to wrap $ref into allOf - this can be used to "add" attributes to a $ref but not override existing attributes.

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

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

Another way is to use replace the $ref with an inline definition.

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 时忽略 Swagger 模式属性 - 为什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！