From 8ad33f35a485d756b8976f100cfdadad9163b922 Mon Sep 17 00:00:00 2001 From: Takashi NATSUME Date: Thu, 20 Sep 2018 20:13:09 +0900 Subject: [PATCH] Add API ref guideline for examples Add guideline for JSON request/response body examples in the API reference. Change-Id: I2dcc2fc1a16cc5dcba7879518a2b101df3576304 --- doc/source/contributor/api-ref-guideline.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/source/contributor/api-ref-guideline.rst b/doc/source/contributor/api-ref-guideline.rst index 4cca9f6e3e0f..384bafa7122f 100644 --- a/doc/source/contributor/api-ref-guideline.rst +++ b/doc/source/contributor/api-ref-guideline.rst @@ -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 ----