how to document nested objects: up to three levels

[eloui...@gmail.com]

Hi Swagger Group,

We have objects nested inside of other objects in our API, sometimes up to three levels deep. Can you tell me how to document these using Swagger 2.0? I found some discussion of this in the forum, but it was dated back in 2013. It seems that a new Swagger has come out since then. 

Here is some sample Swagger 2.0 JSON

        "customer-object-response": {

            "properties": {

                "id": {

                    "type": "integer",

                    "format": "int64",

                    "description": "The unique integer value assigned to the customer",

                    "required": true

                },

                "_authentication": {

                    "type": "", <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<THIS IS AN OBJECT, WHAT TO PUT HERE?

                    "description": "The title of the blog post"

                },

So far, I have not seen any ability to render the nested objects in the swagger-ui. Here is an example of an array:

                "tags": {

                    "type": "array",

                    "description": "An array containing any tags assigned to the blog post",

                    "items": {

                        "type": "string"

                    }

                }

This is a pretty simple array, luckily, where the values are just like this: " string, string, string" So it does not present a huge issue for us, however, I noticed that the swagger-ui renders the above like this, tags (string, optional),

As you can perhaps see, the description is stripped out, in other words, it is not included in swagger-ui. When I click Model Schema, it shows up like this,

"tags": [ "string" ],

It would be maybe a bit nicer if it showed up something more like this:

"tags": [ "string, string, string, ..." ],

But as I say, this specific example is not a huge issue for us. We are more concerned about the first question, which is how to insert the descriptions of the name-value pairs of the nested objects.

Thanks so much for your help!!

Emily

[eloui...@gmail.com]

Hi,

I found something on stack overflow which would seem to describe the syntax.

http://stackoverflow.com/questions/26206685/how-can-i-describe-complex-json-model-in-swagger/26425272#26425272

However, when I follow this, a la:

        "customer-object-response": {

            "properties": {

                "id": {

                    "type": "integer",

                    "format": "int64",

                    "description": "The unique integer value assigned to the customer"

                },

                "addresses": {

                    "type": "array",

                    "items": {

                        "type": "object",

                        "properties": {

                            "url": {

                                "type": "string",

                                "description": ""

                            },

                            "resource": {

                                "type": "string",

                                "description": ""

                            }

                        }

                    }

                }

            }

        }

I get this

So, again, the nested stuff is not rendered or included in swagger-ui.

Thank you,

Emily

[Angeline Loh]

Hi,

In your "addresses" where you have "items", make it point to another reference. 

Meaning 

type": "array",

  "items": {

                        "$ref": "Name of your other definition for item in this array"

[Ron]

Hi Emily,

Apologies for the delayed reply - gmail marked this message as spam for some reason.

So to answer your questions (and I hope I'll cover everything) -

For objects, the "type" should be "object".

The UI currently does not parse objects that are defined inline in other properties. This is a known issue that will be dealt with. Angeline's suggestion should help working around it.

In JSON, " [ ... ] " indicates an array of values, so the notation " [ string ] " is the right notation to say "0 or more string values". " [ string, integer ] " for example would say "0 or more string or integer values". We don't support the latter option in Swagger, but that should give you an idea of why the representation looks like that.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.