[openstack-dev] [horizon][api][docs] Feedback requested on proposed formatting change to API docs
mordred at inaugust.com
Tue May 16 22:13:16 UTC 2017
I read the API docs A LOT. (thank you to all of you who have worked on
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:
You can see the output here:
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
- Does this help, hurt, no difference?
- 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.
More information about the OpenStack-dev