使用 $ref 时忽略了 Swagger 架构属性 - 为什么?
Swagger schema properties ignored when using $ref - why?
我正在尝试为一个时间间隔构建一个 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 "description",而只显示原始时间 "description"。这让我觉得我没有正确地做到这一点。
所以问题是使用模型作为类型是否真的可以像我想做的那样完成。
TL;DR: $ref
兄弟姐妹在 OpenAPI 3.1 中受支持。在以前的 OpenAPI 版本中,$ref
旁边的任何关键字都将被忽略。
OpenAPI 3.1
迁移到 OpenAPI 3.1 后,您的定义将按预期工作。这个新版本完全兼容 JSON Schema 2020-12,它允许 $ref
兄弟姐妹 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
关键字。这些 $refs 旁边的任何其他关键字都将被忽略。
# 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
这里有一些关于 non-schema $ref 兄弟姐妹的 OpenAPI 功能请求,您可以 track/upvote:
- Allow sibling elements with $ref that overrides the references definition
- Allow required as sibling of $ref (like summary/description)
- Extend/override properties of a parameter
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"
我正在尝试为一个时间间隔构建一个 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 "description",而只显示原始时间 "description"。这让我觉得我没有正确地做到这一点。
所以问题是使用模型作为类型是否真的可以像我想做的那样完成。
TL;DR: $ref
兄弟姐妹在 OpenAPI 3.1 中受支持。在以前的 OpenAPI 版本中,$ref
旁边的任何关键字都将被忽略。
OpenAPI 3.1
迁移到 OpenAPI 3.1 后,您的定义将按预期工作。这个新版本完全兼容 JSON Schema 2020-12,它允许 $ref
兄弟姐妹 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
关键字。这些 $refs 旁边的任何其他关键字都将被忽略。
# 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
这里有一些关于 non-schema $ref 兄弟姐妹的 OpenAPI 功能请求,您可以 track/upvote:
- Allow sibling elements with $ref that overrides the references definition
- Allow required as sibling of $ref (like summary/description)
- Extend/override properties of a parameter
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"