如何指定 属性 可以为 null 或带有 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。

我的问题要点：

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

2. 在我的规范中的各个地方 属性 可能是对此类对象的引用或为空。

如何使用不支持 oneOf 或 anyOf?

注意：一些 swagger 实现使用 x-nullable（或类似的）来指定 属性 值可以为 null，但是，$ref 替换 对象及其引用的内容，因此似乎忽略了 x-nullable 的任何使用。

Answer 1

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

等等

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

使用供应商扩展

您可以使用 vendors extensions，例如 x-oneOf 和 x-anyOf。我已经采取了这种艰难的方式：您必须升级所有 used 'swagger tools' 以考虑这些供应商扩展。

就我而言，我们需要 'only' 到 :

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

一年前，也许现在...

重构你的 APIs

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

Answer 2

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 包装到 allOf 中以将 $ref 与其他关键字组合 - 因为 $ref 会覆盖任何同级关键字。这在 OpenAPI 规范存储库中有进一步讨论：Reference objects don't combine well with “nullable”

Answer 3

对于 OpenAPI 3.0 出于某种原因，使用 nullable: true 后跟 allOf 不适用于我正在使用的 OpenAPI 解释器。作为一种解决方法，我最终定义了一个名为 null_type 的 must-be-null 引用，我可以在 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:
    ...