Question

How to specify a property as null or a reference?讨论了如何使用jsonschema将属性指定为null或引用。

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

回顾上面的答案，使用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（或某些）来指定属性值可以为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规范存储库中进一步讨论：Reference objects don't combine well with “nullable”

Answer 2

这样做并不容易。甚至几乎不可能。你的选择：

等待

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

使用供应商扩展

您可以使用vendors extensions，例如 x-oneOf 和 x-anyOf 。我已经采取了这样的措施：您必须升级所有使用过的'swagger工具'，以考虑这些供应商的扩展。

在我的情况下，我们只需要'

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

这是一年前，也许是现在......

重构您的API

许多项目不需要任何一个和一个，为什么不是我们？

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

2 个答案:

等待

使用供应商扩展

重构您的API