Define a mixed data type property in Swagger

Question

I already have a working document that creates documentation using the Swagger-UI project, but I ran into a minor problem.

Mongoose supports the Mixed data type, which is a basically unstructured object that can hold anything. However, according to the Swagger specification, the only possible values ​​for the type property are string , integer , number , boolean and array . I could not find anything in the documentation, on Google, or in open issues for the Swagger-Spec project on GitHub, which would allow mixed data types to be used.

In the Swagger-Spec documentation, where they define type parameters, they refer to the JSON-Schema project. According to the JSON-Schema object specification, there should be an option, but it is not specified as a potential value in the Swagger-Spec.

Does anyone know a way to indicate in a Swagger document that a model property can contain any value (either a single primitive value or an object)?

<strong> Examples

Mongoose schema definition:

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

Using the mongoose model:

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

These are all valid values ​​for two specific properties:

 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 document (snippet):

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

I'm just looking for a way to give the developer the ability to view documentation that a particular property in the model can accept / return any value (primitive variable or object).

Answer 1

In your question, you describe two different use cases.

The first is the use of an array with mixed values, and the second is a specific field that can have any value (be it an object, a primitive, and potentially an array).

Swagger clearly does not support such modeling. There are several reasons for this, but they focus on determinism and language support. Although dynamic languages ​​can more easily support non-deterministic APIs, and weakly typed languages ​​can easily support dynamic types, other languages ​​would suffer. APIs are designed for interoperability, regardless of language, so you should consider these limitations.

While Swagger is understood as a documentation tool, its ecosystem of tools includes solutions that should be able to produce and consume such APIs in almost any language. Obviously, it may not have 100% coverage, but it is trying to avoid known problems.

Swagger 2.0 adds much more flexibility in terms of defining models, even allowing you to create free-form objects (and take notes - objects, not primitives). Although it would be highly discouraged to use in general, there are cases where they simply cannot be avoided, but even strongly typed languages ​​can handle this (I can tell you in detail about the use cases, but this is not relevant to the issue).

As added information - think about it in terms of documentation, and I will use your address field as an example. What you say here, the Wise API, is that the address field is a wildcard. You can take something to him, and he should not be an address, should not have a structure, should not have specific information. If anyone wants, they can use this field to store the kernel launch code. Now, if this is your intention, then just mark the field as a string value, and if someone wants to send a serialized JSON object as a string, it will match exactly the same.