如何指定属性可以为null或带有swagger的引用

Question

如何将属性指定为null或引用？讨论如何使用jsonschema将属性指定为null或引用.

我希望以昂首阔步的方式做同样的事情.

回顾上面的答案,使用jsonschema,可以这样做:

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

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

答案的关键是使用oneOf.

我的问题的关键点:

1. 我有一个复杂的对象,我想保持DRY,所以我把它放在一个定义部分,以便在我的swagger规范中重用:其他属性的值; 响应对象等

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

如何使用不支持的Swagger oneOf或 anyOf？

注意:一些swagger实现使用x-nullable(或某些)指定属性值可以为null,但是,$ref 用它引用的内容替换该对象,因此它将显示任何使用x-nullable被忽略.

Answer 1

在OpenAPI 3.0中，您可以使用：

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

YAML版本：

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

包装$ref成allOf是需要结合$ref其他关键字-因为$ref会覆盖所有的兄弟姐妹的关键字。OpenAPI规范存储库中对此进行了进一步讨论：引用对象与“ nullable”不能很好地结合在一起

Answer 2

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

Answer 3

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

等待

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

使用供应商扩展

您可以使用x-oneOf和x-anyOf等供应商扩展。我已经采取了这种艰难的方式：您必须升级所有使用的“招摇工具”才能考虑到这些供应商的扩展。

就我而言，我们需要“仅”：

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

那是一年前的事了，也许现在……

重构您的 API

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