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

Question

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

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

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

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

例子

Mongoose架构定义:

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."
            },

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

Answer 1

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

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

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

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

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

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