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

How to specify a property as null or a reference? discusses how to specify a property as null or a reference using jsonschema.

我希望用 swagger 做同样的事情.

I'm looking to do the same thing with swagger.

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

To recap the answer to the above, with jsonschema, one could do this:

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

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

答案的关键在于 oneOf 的使用.

The key point to the answer was the use of oneOf.

我的问题的关键点:

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

I have a complex object which I want to keep DRY so I put it in a definitions section for reuse throughout my swagger spec: values of other properties; response objects, etc.

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

In various places in my spec a property may be a reference to such an object OR be null.

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

How do I specify this with Swagger which doesn't support oneOf or anyOf?

注意:一些 swagger 实现使用 x-nullable(或类似的)来指定属性值可以为 null，但是，$ref 替换 对象及其引用的对象，因此看起来对 x-nullable 的任何使用都会被忽略.

Note: some swagger implementations use x-nullable (or some-such) to specify a property value can be null, however, $ref replaces the object with what it references, so it would appear any use of x-nullable is ignored.

推荐答案

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

Not easy to do that. Even almost impossible. Your options :

关于这个point的讨论很长，也许有一天会搞定的……

There is a very long discussion about this point, maybe one day it will be done...

您可以使用 供应商扩展 像 x-oneOf 和 x-anyOf.我已经采取了这种艰难的方式:您必须升级所有使用过的swagger 工具"以考虑这些供应商扩展.

You can use vendors extensions like x-oneOf and x-anyOf. I have already taken this hard way: You must to upgrade all used 'swagger tools' to take into account these vendors extensions.

就我而言，我们只需要:

In my case, we needed 'only' to :

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

一年前，也许现在……

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

Many projects don't need anyOf and oneOf, why not us ?