OpenAPI 3.1

将属性定义为$ref和type: 'null'的anyOf。
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将正常工作。

OpenAPI 3.0

YAML版本：

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

JSON版本：

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

在OAS 3.0中，需要将$ref Package 到allOf中，以便将$ref与其他关键字合并组合-因为$ref会覆盖任何同级关键字。这在OpenAPI规范库中有进一步的讨论：Reference objects don't combine well with “nullable”

对于 OpenAPI 3.0，由于某种原因，使用nullable: true后跟allOf对我使用的OpenAPI解释器不起作用。作为一种变通方法，我最终定义了一个名为null_type的 must-be-null ref，可以在anyOf结构中使用。
就像这样：

allOf:
  - anyOf:
      - $ref: "#/components/schemas/null_type"
      - $ref: "#/components/schemas/your_ref"
  - description: "optionally add other properties here..."

其中：

schemas:
  null_type:
    title: "OpenAPI 3.0 null-type ref"
    description: "for adding nullability to a ref"
    enum: [null]

  your_ref:
    ...

要做到这点并不容易。几乎不可能。您的选择：

等待

关于这个point有很长的讨论，也许有一天会完成.

使用厂商扩展

您可以使用供应商扩展，如 x-oneOf 和 x-anyOf。我已经走上了这条艰难的道路：你必须升级所有使用的'swagger工具'，以考虑这些供应商的扩展。
在我的例子中，我们只需要：

• 为了从源代码中提取swagger API文件，开发了我们自己的带有自定义注解的Jax-RS解析器
• 扩展了swagger-codegen以考虑这些扩展来为我们的客户机生成Java代码
• 开发我们自己的swagger-ui：为了方便这项工作，我们添加了一个预处理步骤，将带有扩展的swagger模式转换为有效的json模式。在JavaScript中找到一个模块来表示json模式比swagger模式更容易。由于缺点，我们放弃了用“试试”按钮测试API的想法。

一年前的事了，也许现在...

重构API

很多项目都不需要anyOf和oneOf，为什么我们不需要？

我在.net6 webAPI中使用Swashbuckle时遇到了类似的问题。我有一个属性，它是一个对象，但也可以是空的。当对象为空时，它无法将其解析。
例如，这起了作用，并使其恢复正常

{
  "Foo":"bar"
  "Details" {
    "Test":"value",
    "Test2":"value"
  }
}

但这并没有使

{
  "Foo":"bar"
  "Details": null
}

为了解决这个问题，我在我的swagger设置中添加了以下内容。

builder.Services.AddSwaggerGen(options =>
{
     options.UseAllOfToExtendReferenceSchemas();
});

产生了以下结果

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