Format for describing objects within objects

970 views
Skip to first unread message

Tom Johnson

unread,
Dec 3, 2015, 2:19:34 PM12/3/15
to Swagger
I'm having trouble understand part of the formatting for the swagger spec. 

Suppose I'm documenting a response, and the model is something like this:

SampleResponse {

   moreDetails {
       "something": "itsvalue"
  }

}


In my description of this response, it looks something like this:

responses:
         200:
           description: |-
             this is my description
           schema: 
             $ref: "#/definitions/SampleResponse"

definitions
  SampleResponse:
    type: object
    properties:
      sampleDetails:
        type: object
        description: description of stuff
        $ref: "#/definitions/moreDetails"

  moreDetails:
    type: object
    properties: 
      something:
        type: string
        description: the value for something


Every time I have an object within an object, do I have to resort to the $ref syntax to define that object, like I've shown here? What if I don't want to use the $ref: "#/definitions/moreDetails", but instead just define that moreDetails object within the same block there? How could I combine the SampleResponse with the moreDetails block?

The problem is that my responses have lots of objects within objects within objects etc. Sometimes it gets 7 levels deep. I'm okay with breaking out the objects in the definitions area like I've shown here, but if there's a way to easily combine them, I think that might make more sense (though it wouldn't enable re-use).




Tom Johnson

unread,
Dec 3, 2015, 4:40:02 PM12/3/15
to Swagger
I have a follow up question. There seems to be a difference in the Model and Model Schema display. The Model Schema shows nested objects, but the Model doesn't nest the objects. 

As an example, look at the http://petstore.swagger.io/#!/pet/updatePet body. The Model Schema shows category as a nested object, but when you switch to the Model view, Category is also broken out into its own object as well below.

I assume the Model view never shows nested objects inside other objects?

Ron

unread,
Dec 3, 2015, 5:38:50 PM12/3/15
to Swagger

Hi Tom,

You can definitely define sub-object inline. It’s pretty much taking the content of the $ref and pouring it in place.
Taking your example:

definitions
  SampleResponse:
    type: object
    properties:
      sampleDetails:
        type: object
        properties: 
          something:
            type: string
            description: the value for something

The UI display changes based on how easy it is to show everything - it’s more about UX than it is about the structure behind.

As a side note, keep in mind that you cannot have additional properties alongside $ref like you have in the example above. Their values would be completely ignored.

Tom Johnson

unread,
Dec 3, 2015, 6:22:03 PM12/3/15
to swagger-sw...@googlegroups.com
Awesome! That works. This makes my life much simpler. Thanks for your help Ron.

Tom

---------------------
blog: idratherbewriting.com
twitter: tomjohnson

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/XfKi0_2HEYY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Tom Johnson

unread,
Dec 4, 2015, 7:35:54 PM12/4/15
to swagger-sw...@googlegroups.com
I ran into a problem. With the Swagger UI, the "model" view for objects within objects seems to not work as expected. When I specify a title, the inline_id changes to the title. But the object gets blanked out.

My definition has this structure:

definitions:

  body:
    type: object
    required:
      - inputIds
    title: body
    properties:
      inputIds:
          type: object
          description: My description here
          properties:
            identifier code: 
              type: string
              example: value

The Swagger UI shows "inline_model" for the object within the object.

inputIds (inline_model): My description here ...
}
inline_model {
identifier code (string, optional)
}

So I added a title, like this:

inputIds:
        type: object
        description: My description here
        title: My IDs
        properties:
          identifier code: 
            type: string
            example: value

Now the Swagger UI renders the model view like this:

inputIds (My IDs): My description here...
}
My IDs {
}

What I expected was this:

inputIds (My IDs): My description here ...
}
My IDs {
identifier code (string, optional)
}

The contents of My IDs (identifier code (string, optional)) is getting stripped out when I add a title property. Is this a bug, or am I doing something wrong? It works fine if I use $ref instead of nesting objects like this.

Thanks,

Tom


---------------------
blog: idratherbewriting.com
twitter: tomjohnson

On Thu, Dec 3, 2015 at 2:38 PM, Ron <r...@swagger.io> wrote:

--

Tom Johnson

unread,
Dec 7, 2015, 2:07:35 PM12/7/15
to Swagger
Am I right to think the only workaround here is to break out the nested objects into the $ref approach? At least that approach named the object rather than using "Inline model".

Ron

unread,
Dec 7, 2015, 2:36:39 PM12/7/15
to Swagger
Yeah, sorry about that. It does sound like a bug.

Tom Johnson

unread,
Dec 7, 2015, 3:46:29 PM12/7/15
to swagger-sw...@googlegroups.com
Thanks for the confirmation Ron.

---------------------
blog: idratherbewriting.com
twitter: tomjohnson

Reply all
Reply to author
Forward
0 new messages