Object description is not shown in array description

[vkaderabek]

I have RAML file contains something like:

#%RAML 1.0
title: Test Case
version: 1.0
mediaType: [ application/json ]

types:
  Obj1:
    type: object
    properties:
      item1:
        type: number
        description: item 1 description
      item2:
        type: integer
        minimum: 1
        required: false
        description: item 2 description
    description: Obj1 description

  Obj2:
    type: object
    properties:
      arrayAttribute:
        type: Obj1[]
        required: false

I expect that the description for array will be get from object from which is array composed.
As is shown here

It should be good if you want to use array of objects as attribute in multiple objects (it will not be necessary to copy description to each usage).

[jarrodek]

Hi,

thank you for issue report.

I am not sure if that's the right usage. obj2 > arrayAttribute has it's own field for documentation and should be used for populating the description field. API console would generate a description that isn't there. I'm rather skeptical for the console to generate anything that is not there.

@jstoiko any input on this? Would you agree with @vkaderabek? You know my opinion on generating content in the console.

[vkaderabek]

Hi.

Maybe it is not necessary to put there comment from object, but for now there is not mentioned array of which objects it is. It could be work around how to get to description.

Or maybe exists some another solution how to solve this issue. (I do not count copy description from object to all usage as array of this object - there is a big chance to forget in few places update description when changing object description.)

[jarrodek]

I mean I don't disagree with you. This place could have if not the description then at least an explanation. I believe there is something in generated model we can put. I am just not sure what that would be. I am not sure if the description is the best idea. Let's wait what @jstoiko has to say.

[jstoiko]

It seems like API console (intentionally?) hides individual object's information and instead, only displays the inner properties of the object.

I hope I am understanding correctly. If so, then I would argue that it makes sense NOT to display Obj1's description in this case because the only description that may appear in this case is arrayAttribute's description which is currently missing.