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