docs/api-reference/api-doc-template.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2020 Deutsche Telekom AG.
   4
   5
   6 .. This is a template to document new APIs for CDS blueprint processor
   7
   8 .. make use of tabs whenever it fits
   9
  10 Module
  11 ====================
  12
  13 Resource 1
  14 ------------
  15
  16 General description about the resource.
  17
  18
  19 Method 1 Endpoint 1
  20 ~~~~~~~~~~~~~~~~~~~~
  21
  22 <method> ``<path>``
  23 ......................
  24
  25 Method 1 Endpoint 1 description
  26
  27 Request
  28 ...........
  29
  30 .. code-block:: curl
  31    :caption: **(sample) request**
  32
  33    request command
  34
  35 .. can be split into Header and Body description if thats more suitable.
  36 .. If its split, Header requires content-type definition, Body requires example payload
  37
  38 **Request Path Parameters:**
  39
  40 .. list-table::
  41    :widths: 20 20 20 40
  42    :header-rows: 1
  43
  44    * - Parameter
  45      - Type
  46      - Required
  47      - Description
  48    * - value 1
  49      - value 2
  50      - value 3
  51      - value 4
  52    * - value 1
  53      - value 2
  54      - value 3
  55      - value 4
  56
  57 **Request Query Parameters:**
  58
  59 .. list-table::
  60    :widths: 20 20 20 40
  61    :header-rows: 1
  62
  63    * - Parameter
  64      - Type
  65      - Required
  66      - Description
  67    * - value 1
  68      - value 2
  69      - value 3
  70      - value 4
  71    * - value 1
  72      - value 2
  73      - value 3
  74      - value 4
  75
  76 **Request Body Parameters:**
  77
  78 .. list-table::
  79    :widths: 20 20 20 40
  80    :header-rows: 1
  81
  82    * - Parameter
  83      - Type
  84      - Required
  85      - Description
  86    * - value 1
  87      - value 2
  88      - value 3
  89      - value 4
  90    * - value 1
  91      - value 2
  92      - value 3
  93      - value 4
  94
  95 Success Response(s)
  96 ......................
  97
  98 HTTP Status 202 OK
  99
 100 Headers:
 101 ``Content-Type:application/json``
 102
 103 .. code-block:: json
 104    :caption: **(sample) response body and/or response schema**
 105
 106    (sample) response (can be {})
 107
 108 **Success Response Parameters:**
 109
 110 .. list-table::
 111    :widths: 30 30 40
 112    :header-rows: 1
 113
 114    * - Parameter
 115      - Type
 116      - Description
 117    * - value 1
 118      - value 2
 119      - value 3
 120    * - value 1
 121      - value 2
 122      - value 3
 123
 124 Error Response(s)
 125 ......................
 126
 127 HTTP Status 404 The requested resource could not be found
 128
 129 .. code-block:: json
 130    :caption: **sample error response**
 131
 132    error response
 133
 134 **Error Response Parameters:**
 135
 136 .. list-table::
 137    :widths: 30 30 40
 138    :header-rows: 1
 139
 140    * - Parameter
 141      - Type
 142      - Description
 143    * - value 1
 144      - value 2
 145      - value 3
 146    * - value 1
 147      - value 2
 148      - value 3
 149
 150 .. or just table for responses with HTTP code, description and schema
 151
 152 Consumes
 153 ............
 154
 155 ``application/json``
 156
 157 Produces
 158 ...........
 159
 160 ``application/json``
 161
 162
 163 Functional Description
 164 ..............................
 165
 166 What does the API do in detail?
 167
 168 Technical Description
 169 ...........................
 170
 171 Called class, methods, other hints.
 172
 173 Related topics
 174 ......................
 175
 176  * Topic 1
 177  * Topic 2
 178
 179
 180 Method 2 Endpoint 1
 181 ~~~~~~~~~~~~~~~~~~~~
 182
 183 <method> ``<path>``
 184 ......................
 185
 186 Method 2 Endpoint 1 description
 187
 188 ..
 189
 190
 191 Method 1 Endpoint 2 (Subresource):
 192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 193
 194 <method> ``<path><subpath>``
 195 ..............................
 196
 197
 198 ..
 199
 200 Resource 2
 201 --------------------
 202
 203
 204 ..
 205