Question

我已经有一个工作的swagger文档，使用Swagger-UI项目生成文档，但我遇到了一个小问题。

Mongoose支持Mixed的数据类型，它基本上是一个可以包含任何内容的非结构化对象。但是，根据Swagger规范，属性type的唯一可能值为string，integer，number，boolean和{{ 1}}。我一直无法在文档，Google上或GitHub上的Swagger-Spec项目的公开问题中找到允许混合数据类型的任何内容。

在Swagger-Spec文档中，他们定义了array选项，它们引用了JSON-Schema项目。根据JSON-Schema规范type应该是一个选项，但它没有被列为Swagger-Spec中的潜在值。

有没有人知道在Swagger文档中指明模型的属性可以包含任何值（单个原始值或对象）的方法？

实施例

Mongoose架构定义：

object

猫鼬模型的用法：

var sampleSchema = new mongoose.Schema({
    lookupCodes : { type: [mongoose.Schema.Types.Mixed] },
    address: { type: mongoose.Schema.Types.Mixed }
});

mongoose.model('Sample', sampleSchema);

这些是两个定义属性的有效值：

var Sample = mongoose.model('Sample');
var doc = new Sample();

Swagger 1.2文档（摘录）：

doc.lookupCodes = ['A', 'B', 3, 4, 5, 'F'];

doc.lookupCodes = ['A', { code: '123' }, 5];

doc.address = '123 Main St., San Jose, CA, 95125';

doc.address = { street: '123 Main St.', city: 'San Jose', state: 'CA', postalCode: '95125'}

我只是想找一种方法让开发人员查看文档，知道模型中的特定属性可以接受/返回任何值（原始变量或对象）。

Answer 1

在您的问题中，您描述了两个不同的用例。

第一个是使用具有混合值的数组，第二个是可以具有任何值的特定字段（无论是对象，基元还是可能是数组）。

Swagger明确表示不支持此类建模。有几个原因，但他们专注于决定论和语言支持。虽然动态语言可以更轻松地支持非确定性API，而弱类型语言可以轻松支持动态类型，但其他语言会受到影响。 API旨在实现互操作性，与语言无关，因此您必须考虑这些限制。

虽然Swagger是一种文档工具，但其工具生态系统包括需要能够以几乎任何语言生成和使用此类API的解决方案。显然，它不能100％覆盖，但它试图避免已知问题。

Swagger 2.0在定义模型方面增加了更大的灵活性，甚至允许自由形式的对象（并且做注释 - 对象，而不是基元）。虽然一般情况下不建议使用它，但有些情况下它是无法避免的，但即使是强类型语言也可以处理它（我可以详细说明用例，但它并不相关到手头的问题）。

作为补充信息 - 从文档的角度考虑它，我将以address字段为例。你在这里说的是 API Wise ，地址字段是通配符。您可以接受任何，并且它不必是地址，不必具有结构，不必具有特定信息。如果有人想要，他们可以使用该字段存储核启动代码。现在，如果这是你的意图，那么只需将字段标记为字符串值，如果有人想将序列化的JSON对象作为字符串发送，它也适合。

在Swagger中定义具有混合数据类型的属性

1 个答案: