diff options
author | 2020-11-18 15:53:30 +0100 | |
---|---|---|
committer | 2020-11-18 15:56:37 +0100 | |
commit | b1da7d99a9976016dedf6ff53a526b51de646c9c (patch) | |
tree | 1f9c1853940a17e1cafbf153927daecefa4f2837 /docs/api-reference/api-doc-template.rst | |
parent | 17707e6531d3986e43020725a3de06351d387226 (diff) |
CDS Api reference add index, template, first APIs
Issue-ID: CCSDK-2992
Change-Id: Iad8524cce702deb7f35650b9bd69b6690c0ecc6d
Signed-off-by: JakobKrieg <jakob.krieg@bcmsolutions.de>
Diffstat (limited to 'docs/api-reference/api-doc-template.rst')
-rw-r--r-- | docs/api-reference/api-doc-template.rst | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/docs/api-reference/api-doc-template.rst b/docs/api-reference/api-doc-template.rst new file mode 100644 index 000000000..54e587fd6 --- /dev/null +++ b/docs/api-reference/api-doc-template.rst @@ -0,0 +1,205 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + + +.. This is a template to document new APIs for CDS blueprint processor + +.. make use of tabs whenever it fits + +Module +==================== + +Resource 1 +------------ + +General description about the resource. + + +Method 1 Endpoint 1 +~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path>`` +...................... + +Method 1 Endpoint 1 description + +Request +........... + +.. code-block:: curl + :caption: **(sample) request** + + request command + +.. can be split into Header and Body description if thats more suitable. +.. If its split, Header requires content-type definition, Body requires example payload + +**Request Path Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +**Request Query Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +**Request Body Parameters:** + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Parameter + - Type + - Required + - Description + * - value 1 + - value 2 + - value 3 + - value 4 + * - value 1 + - value 2 + - value 3 + - value 4 + +Success Response(s) +...................... + +HTTP Status 202 OK + +Headers: +``Content-Type:application/json`` + +.. code-block:: json + :caption: **(sample) response body and/or response schema** + + (sample) response (can be {}) + +**Success Response Parameters:** + +.. list-table:: + :widths: 30 30 40 + :header-rows: 1 + + * - Parameter + - Type + - Description + * - value 1 + - value 2 + - value 3 + * - value 1 + - value 2 + - value 3 + +Error Response(s) +...................... + +HTTP Status 404 The requested resource could not be found + +.. code-block:: json + :caption: **sample error response** + + error response + +**Error Response Parameters:** + +.. list-table:: + :widths: 30 30 40 + :header-rows: 1 + + * - Parameter + - Type + - Description + * - value 1 + - value 2 + - value 3 + * - value 1 + - value 2 + - value 3 + +.. or just table for responses with HTTP code, description and schema + +Consumes +............ + +``application/json`` + +Produces +........... + +``application/json`` + + +Functional Description +.............................. + +What does the API do in detail? + +Technical Description +........................... + +Called class, methods, other hints. + +Related topics +...................... + + * Topic 1 + * Topic 2 + + +Method 2 Endpoint 1 +~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path>`` +...................... + +Method 2 Endpoint 1 description + +.. + + +Method 1 Endpoint 2 (Subresource): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +<method> ``<path><subpath>`` +.............................. + + +.. + +Resource 2 +-------------------- + + +.. + |