RFE: Request and Response samples must be arranged

[Lana]

In the API Documentation, the request and response parameters are tabulated followed by the json samples of the request and response. It is quite confusing sometimes to differentiate between the request and the response samples. So, the samples have to be documented under request and response parameters respectively.

[Anne Gentle (annegentle)]

Pretty sure this can't be fixed in openstack-manuals repo, unless you're thinking this belongs in the contributor guide? Should this be a documented style guidance for API reference content?

[Karen Bradshaw (kbhawkey)]

Typically, the request parameter table precedes the request example. If there is no request body, then text such as 'No expected request body for this method' could be in place of the sample. This piece of information is probably missing in a number of instances. Another idea would be to separate the query, header, and path parameters from the request parameter table, and list these parameters in text format above the request body parameter table. This may provide more information on how to create the actual request string.
The response parameter table and response example currently follow the request information.
The examples should have a sub-title identifying the example.