Open Stack

On Tue, May 16, 2017 at 05:13:16PM -0500, Monty Taylor wrote:
> Hey all!
> 
> I read the API docs A LOT. (thank you to all of you who have worked
> on writing them)
> 
> As I do, a gotcha I hit up against a non-zero amount is mapping the
> descriptions of the response parameters to the form of the response
> itself. Most of the time there is a top level parameter under which
> either an object or a list resides, but the description lists list
> the top level and the sub-parameters as siblings.
> 
> So I wrote a patch to os-api-ref taking a stab at providing a way to
> show things a little differently:
> 
> https://review.openstack.org/#/c/464255/
> 
> You can see the output here:
> 
> http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/
> 
> If you go expand either the GET / or the GET /servers/details
> sections and go to look at their Response sections, you can see it
> in action.
> 
> We'd like some feedback on impact from humans who read the API docs
> decently regularly...
> 
> The questions:
> 
> - Does this help, hurt, no difference?

It helps.

> - servers[].name - servers is a list, containing objects with a name
> field. Good or bad?

Good.

> - servers[].addresses.$network-name - addresses is an object and the
> keys of the object are the name of the network in question.

This is a little bit confusing but still understandable.

my $0.0002 

Qiming
> Thanks!
> Monty