我已经有一个有效的swagger文档,可以使用Swagger-UI项目生成文档,但是我遇到了一个小问题。
猫鼬支持的数据类型Mixed
,基本上是可以包含任何内容的非结构化对象。然而,根据扬鞭规范的唯一可能的值属性的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."
},
我只是在寻找一种让开发人员查看文档的方法,该方法知道模型中的特定属性可以接受/返回任何值(原始变量或对象)。
在您的问题中,您描述了两个不同的用例。
第一个是混合值数组的使用,第二个是可以具有任何值的特定字段(可以是对象,基元和可能的数组)。
Swagger明确不支持这种建模。这样做的原因有很多,但它们集中在确定性和语言支持上。虽然动态语言可以更轻松地支持非确定性API,而弱类型语言可以轻松地支持动态类型,但其他语言也会因此遭受损失。API旨在实现互操作性,并且与语言无关,因此您必须考虑这些限制。
尽管Swagger旨在作为一种文档工具,但其工具生态系统包括一些解决方案,这些解决方案实际上需要能够以任何语言生成和使用此类API。显然,它不能具有100%的覆盖率,但是它试图避免已知问题。
Swagger 2.0在定义模型方面增加了更多的灵活性,甚至允许使用自由格式的对象(并且要注意-对象,而不是基元)。虽然不建议一般使用它,但是在某些用例中,它是不可避免的,但是即使是强类型的语言也可以处理它(我可以详细说明用例,但与该问题无关)手)。
作为补充信息,请从文档角度考虑。我将以您的address
字段为例。您在这里所说的API Wise是地址字段是通配符。您可以接受任何内容,它不必是地址,不必具有结构,也不必具有特定信息。如果有人愿意,他们可以在该字段中存储核发射代码。现在,如果这是您的意图,那么只需将字段标记为字符串值,如果有人想将序列化的JSON对象发送为字符串,则它也将适合。
本文收集自互联网,转载请注明来源。
如有侵权,请联系[email protected] 删除。
我来说两句