On 05/17/2017 10:14 AM, Joe Topjian wrote:
On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <mord...@inaugust.com
<mailto:mord...@inaugust.com>> 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/
<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/
<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. It seems noisy at first glance, but the information being
denoted is important. It's one of those situations where once you start
reading deeper into the information, this kind of markup makes the API
more understandable more quickly.
Awesome. Thanks!
- servers[].name - servers is a list, containing objects with a name
field. Good or bad?
- servers[].addresses.$network-name - addresses is an object and the
keys of the object are the name of the network in question.
Again, these seem noisy at first, but having parsed complex paths,
especially the above address info, by dumping variables too many times,
I really appreciate the above syntax.
Going even further:
servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr
looks a mess, but I can see how exactly to navigate to the leaf as well
as understand what types make up the path. Being able to succinctly
(relatively/subjectively speaking) describe something like the above is
very helpful. This definitely gets my support.
Sweet. thanks for the feedback! I just pushed up a new rev yesterday
based on some feedback from Anne:
http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/
That adds <strong> tags around the leaf element. so basically:
servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr
becomes
servers[].addresses.$network-name[].**OS-EXT-IPS-MAC:mac_addr**
which I hope will ease any confusion when leaf elements have punctuation
in their names - like OS-EXT-IPS-MAC:mac_addr
__________________________________________________________________________
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
