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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
