Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Object description is not shown in array description #614

Open
vkaderabek opened this issue Aug 5, 2019 · 4 comments
Open

Object description is not shown in array description #614

vkaderabek opened this issue Aug 5, 2019 · 4 comments

Comments

@vkaderabek
Copy link

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
Snímek obrazovky 2019-08-05 v 14 16 19

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
Copy link
Contributor

jarrodek commented Aug 6, 2019

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
Copy link
Author

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
Copy link
Contributor

jarrodek commented Aug 6, 2019

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
Copy link

jstoiko commented Aug 15, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants