allow list models and json params and display subTypes

[ganeshjung]

Hi,
We would love to use swagger for our API documentation, but there are 3 shortcomings that don't make this work:

• model objects can only be objects, not lists, so JavaScript [] cannot be represented, only {}
• requests cannot have type "json", so and API with the JSON encoded params in the POST body cannot be represented.
• swagger-ui doesn't display parent properties

We are ready to pay someone from the community to provide the following extensions and kindly ask for offers. Please provide the correct place for this request if you consider swagger-spec as an incorrect place.

Provide the following extensions to swagger and create pull requests on github:

• Extend the swagger-spec in chapter 5.2.7 so that a model object can contain a field "items" instead of "properties" and implement the extension. If a model has got items, it's JavaScript representation is [...] instead of {...}. This will allow the definition of array models and also nesting of array models. The implementation must also include an appropriate display format for array models in swagger-ui.
• Extend swagger-spec to allow a paramType "json" to describe request params that are encoded as JSON object in the request's POST body. Implement the param-type json so that the "Try it!" button from swagger-ui creates requesty with parameters encoded as JSON object in the request's POST body.
• Extend swagger-ui to display the properties of parent models. Models can be defined to have subTypes, but swagger-ui currently doesn't display the properties within the subTypes.

[webron]

Regarding model definition, there's no need for that. Even in JSON/JS there's a distinct difference between an object and a list. An object is represented by {} and a list by []. Models represent objects and not lists.
If you want to use a list of objects, that's simple. Have the type of the operation/parameter/property be "array" and the "items" have a "$ref" to the model definition. That effectively produces the result you're looking for.

Regarding the "json" type - if you declare that the operation's "consumes" field is "application/json", it basically tells the user that the model needs to be represented in a JSON format.

As for swagger-ui, if you've noticed a bug where the support for subtypes is lacking, please open an issue on https://github.com/wordnik/swagger-ui and it will get fixed.

Does this answer your requirements?

[ganeshjung]

Hey webron,

Thank you for the quick answer.

1.) We want to use model lists to define this case:

MyListClassA: {
items: {
"$ref": "MyListClassB"
}
}

MyListClassA: {
items: {
"type": "string"
}
}

We have nested arrays and we think this would be the cleanest solution to model this with swagger.

2.) We really like the "Try it!" button from swagger-ui, but it doesn't produce the correct output for our application though the "consumes" field is "application/json".

Our application requires JSON objects in the POST body and we still think the "json" paramType is necessary. How should the button react if the "consumes" field is "[application/json, text/html]"? With a "json" param type it would even be possible to have some query params and some others JSON encoded in the POST body.

3.) Sure the requirement to display the properties of parent models would need to go to swagger-ui. We were looking for someone from the community who is happy to earn some money with this, solve all three problems at once and push the results into the respective repositories.

Kind regards,
Ganesh

[webron]

1. I don't understand the sample you're providing. You're defining the same model, each time with a different array in it. That's not a nested array or anything. If what you wanted to define was this:

MyListClassA: {
items: {
"$ref": "MyListClassB"
}
}

MyListClassB: {
items: {
"type": "string"
}
}

You can do that right now. However, keep in mind this is not a list of lists but rather a list of objects containing a list in them (basically, the difference between [[...], [...], [...]] and [{[...]}, {[...]}, {[...]}]).

Currently, nested arrays ([[...], [...], [...]]) are not supported by Swagger, though there's a ticket on it.

2. consumes/produces translates to HTTP headers which REST depends on. It affects the content of the request and response, which as far as I can tell affects the body but means nothing regarding the query/path parameters. If you offer two options for consumption as stated by your example, it means the user has to pick which one they'd want to use (swagger-ui should show a drop-down with the options) and the appropriate HTTP header will be sent to notify the server of the content type.
   In my opinion, sending objects (which would require a structure such as JSON or XML) as a query parameter should be avoided in general for various reasons. That said, it doesn't mean it's not possible to do so, but there's currently no way to define in specifically. The "consumes" field affects the operation and follows the HTTP definitions. If you have a specific issue with swagger-ui not behaving as you expect it to, please open an issue about it on swagger-ui and it will be attended.

3. Making a change as you request in number 1 is not trivial as it requires making changes to the spec itself. Obviously, you can always fork the swagger project and do as you please with them (the license we use is permissive), but it won't be easy to add this back into Swagger once the changes are done. Keep in mind this will also break third party tools that you may want to provide your clients with (client generators, ui's, automatic tests and so on).
   Nevertheless, the right place to offer paid services about it would be in our mailing list. Another option is to contact @fehguy directly and discuss it with him.

[ganeshjung]

Hi webron,

The speed of your responses is amazing and I'm very pleased with it.

for 1) you are right with your guess. We had a typo in our example, which is very annoying considering the example's size. I don't understand why you say "you can do this right now". As far as I know a model currently cannot have "items", but only can have "properties". The idea of "items" is to have a class representing [...], thus an array with $ref to this class would be [[...], ..., [...]]. Wouldn't this be a great way to introduce nested arrays into swagger without nesting complex types?

for 2) I understand that the solution may be on swagger-ui side by providing a better interpretation of the consumes field (maybe in combination with paramType "body"?).

This said we will contact @fehguy for the two swagger-ui improvements. Have I been able to explain my idea of an "items" field in model object for nested array?

[webron]

1. You can have a model with a property of type array. Even if we introduced nested arrays, it would be by having an array of arrays. What you suggest is just another way of representing it and is not really required as an array of arrays would cover it (no point defining two methods of nested arrays). A model is an object. An object is not an array but can contain an array (thus the {...} representation). An array is a list of either primitives or objects and is not a model on its own (thus the [...] representation).
   Again, nested arrays are simply not supported by the current specification, but you can follow on Add support for nested arrays #40 to see if and when it is added. The idea you suggest is understood but it is not required (and we try to follow a structure similar to JSON schema's definition and your suggestion just doesn't follow it).

2. Currently, the swagger-ui should have no issues dealing with "application/json" mime type for consumption. If you encounter an issue with it, please open it on swagger-ui directly.

[ganeshjung]

ok, thank you so much for your help. switching to swagger-ui ...