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

我正在尝试为一个时间间隔构建一个招摇过市的模型，使用一个简单的字符串来存储时间（我知道还有datetime）：

出于某种原因，生成的HTML不显示上下界的“描述”，而只显示原始时间的“描述”。这让我觉得我做得不对

---

所以问题是，使用一个模型作为一个类型是否真的可以像我试图做的那样；DR:

$ref

在OpenAPI 3.1中支持同级。在以前的OpenAPI版本中，

$ref

旁边的任何关键字都将被忽略

OpenAPI 3.1 当迁移到OpenAPI 3.1时，您的定义将按预期工作。这个新版本与JSON模式2020-12完全兼容，它允许模式中的

$ref

同级

openapi:3.1.0
...
组件：
模式：
时间：
类型：字符串
描述：24小时格式的时间“hh:mm”。
时间间隔：
类型：对象
特性：
lowerBound：
#------这将在OAS 3.1中起作用------#
$ref:“#/components/schemas/Time”
描述：时间间隔的下限。
默认值：“00:00”
上限：
#------这将在OAS 3.1中起作用------#
$ref:“#/components/schemas/Time”
描述：时间间隔的上限。
默认值：“24:00”

在架构之外-例如，在响应或参数中-$refs仅允许同级

摘要
和
描述
关键字。这些$refs旁边的任何其他关键字都将被忽略

#openapi:3.1.0
#这是支持的
参数：
-$ref:“#/components/parameters/id”
描述：实体ID
#这是不受支持的
参数：
-$ref:“#/components/parameters/id”
必填项：true

OpenAPI 2.0和3.0.x
在这些版本中，
$ref
通过将自身及其所有同级元素替换为它所指向的定义来工作。这就是为什么

lowerBound：
$ref:“#/定义/时间”
描述：时间间隔的下限。
默认值：“00:00”

变成

lowerBound：
类型：字符串
描述：24小时格式的时间“hh:mm”。



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

lowerBound：
所有：
-$ref:“#/定义/时间”
描述：时间间隔的下限。
默认值：“00:00”

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

定义：
时间间隔：
类型：对象
特性：
lowerBound：
type:string#如果本例中的
TimeInterval
是一个生成招摇过市定义的类--该类可能也有招摇过市注释--您知道如何对该类和/或注释进行编码，以便它生成此答案中的任一解决方法吗（即使用
allOf
，或使用内联定义而不是
$ref
）？@ChrisW我不知道，对不起。试试注释。谢谢。已经有这样一个问题（），我想知道您是否碰巧知道。我想我会尝试通过（而不是注释）实现它为该类构造一个模型实例，并通过ModelResolver注入该自定义模型实例。@Helen，您能否提供OpenAPI的官方文档链接，说明正式支持使用$ref？根据官方文档，go for OpenAPI不支持使用$ref。
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"