openstack/nova
Code Issues Proposed changes

Add API ref guideline for examples

Browse Source 
Add guideline for JSON request/response body examples
in the API reference.

Change-Id: I2dcc2fc1a16cc5dcba7879518a2b101df3576304
This commit is contained in:
Takashi NATSUME 2018-09-20 20:13:09 +09:00
parent 7a76d0c71d
commit 8ad33f35a4
1 changed files with 13 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/source/contributor/api-ref-guideline.rst
View File

@ -213,9 +213,20 @@ The order of parameters in the parameter file has to be kept as follows:
Example
-------
.. TODO::
One or more examples should be provided for operations whose request and/or
response contains a payload. The example should describe what the operation
is attempting to do and provide a sample payload for the request and/or
response as appropriate.
Sample files should be created in the ``doc/api_samples`` directory and inlined
by inclusion.
The guideline for request/response JSON bodies should be added.
When an operation has no payload in the response, a suitable message should be
included. For example::
There is no body content for the response of a successful DELETE query.
Examples for multiple microversions should be included in ascending
microversion order.
Body
----