RFE: Request and Response samples must be arranged

Bug #1604216 reported by Lana on 2016-07-19
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
openstack-doc-tools
Medium
Unassigned
openstack-manuals
Medium
Unassigned

Bug Description

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.

Changed in openstack-manuals:
status: New → Triaged
importance: Undecided → Medium
Anne Gentle (annegentle) wrote :

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?

affects: openstack-manuals → openstack-doc-tools
Changed in openstack-manuals:
status: New → Confirmed
importance: Undecided → Medium
Karen Bradshaw (kbhawkey) wrote :

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.

Changed in openstack-manuals:
status: Confirmed → Won't Fix
tags: added: api-doc
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers