openstackdocstheme

RFE: Request and Response samples must be arranged

Bug #1604216 reported by Lana
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
openstack-manuals
Won't Fix
Medium
Unassigned
openstackdocstheme
Triaged
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.

Tags: api-doc
KATO Tomoyuki (kato-tomoyuki)
Changed in openstack-manuals:
status: New → Triaged
importance: Undecided → Medium
Revision history for this message
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
Revision history for this message
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.

Alexandra Settle (alexandra-settle)
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  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.