swagger - 如何指定一个属性可以是空的，也可以是带有 Swagger 的引用

Question

How to specify a property as null or a reference?讨论如何使用 jsonschema 将属性指定为 null 或引用。
我希望用 Swagger 来做同样的事情。
回顾上面的答案，使用 jsonschema，可以这样做:

{
   "definitions": {
      "Foo": {
         # some complex object
      }
   },

   "type": "object",
   "properties": {
      "foo": {
         "oneOf": [
            {"$ref": "#/definitions/Foo"},
            {"type": "null"}
         ]
      }
   }
}

答案的关键是使用 oneOf .
我的问题的关键点:

我有一个复杂的对象，我想保持干燥，所以我把它放在
在我的 Swagger 规范中重用的定义部分:其他属性的值；响应对象等

在我的规范中的各个地方
property 可以是对此类对象的引用，也可以为 null。

如何使用不支持 oneOf 的 Swagger 指定它或者 anyOf ?
注意:一些 Swagger 的实现使用 x-nullable (或类似的)指定属性值可以为空，但是， $ref用它引用的对象替换对象，所以它会出现任何使用 x-nullable被忽略。

Answer 1

开放API 3.1
将属性定义为 anyOf的$ref和 type: 'null' .
YAML 版本:

foo:
  anyOf:
    - type: 'null'   # Note the quotes around 'null'
    - $ref: '#/components/schemas/Foo'

JSON版本:

"foo": {
    "anyOf": [
        { "type": "null" },
        { "$ref": "#/components/schemas/Foo" }
    ]
}

为什么使用 anyOf而不是 oneOf ? oneOf如果引用的模式本身允许空值，则验证将失败，而 anyOf将工作。
开放API 3.0
YAML 版本:

foo:
  nullable: true
  allOf:
  - $ref: '#/components/schemas/Foo'

JSON版本:

"foo": {
    "nullable": true,
    "allOf": [
        { "$ref": "#/components/schemas/Foo" }
    ]
}

在 OAS 3.0 中，包装 $ref进入 allOf需要结合 $ref与其他关键字 - 因为 $ref覆盖任何同级关键字。这将在 OpenAPI 规范存储库中进一步讨论: Reference objects don't combine well with “nullable”