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

Question

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

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

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

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

例子

猫鼬模式定义：

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();

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

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'}

Swagger 1.2 文档（片段）：

"models": {
    "Sample": {
        "properties": {
            "lookupCodes": {
                "type": "array",
                "items": {
                    "type": "??????"
                },
                "description": "An array of lookup codes. Codes can be strings, numbers or an object containing the `code` property."
            },
            "address": {
                "type": "??????",
                "description": "An address. This value can be a single string, containing all the elements of the address together, or it can be a structured object with each of the elements as separate properties of the object."
            },

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

Answer 1

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

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

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

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

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

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

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

Define a property with a mixed data type in Swagger

mongoose

mongodb

swagger