Convert API docs to OpenAPI format #839

dsmrreader · Jan 16, 2020 · 62493a0 · 62493a0
1 parent 12ce89d
commit 62493a0
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 35 deletions.
diff --git a/dsmr_frontend/static/dsmr_frontend/postman/collection.json b/dsmr_frontend/static/dsmr_frontend/postman/collection.json
@@ -9,7 +9,7 @@
 			"name": "v1 API (datalogger)",
 			"item": [
 				{
-					"name": "Remote datalogger",
+					"name": "Create DSMR reading by telegram",
 					"request": {
 						"method": "POST",
 						"header": [

diff --git a/dsmr_frontend/static/dsmr_frontend/yaml/swagger.yaml b/dsmr_frontend/static/dsmr_frontend/yaml/swagger.yaml
@@ -12,12 +12,6 @@ info:
     - [Download Postman collection](/static/dsmr_frontend/postman/collection.json)
     - [Download Postman environment variables](/static/dsmr_frontend/postman/variables.json)
 
-    ## Datetime string format
-    Timezone aware ``YYYY-MM-DDThh:mm[:ss][+HH:MM|-HH:MM|Z]``, for example:
-    - ``2020-01-15T10:00:00Z`` (UTC)
-    - ``2020-01-15T12:00:00+01`` (CET)
-    - ``2020-01-15T12:00:00+02`` (CEST)
-
 externalDocs:
   description: DSMR-reader general documentation
   url: 'https://dsmr-reader.readthedocs.io/'
@@ -46,13 +40,16 @@ paths:
       tags:
         - Remote datalogger
       operationId: v1_datalogger_dsmrreading
-      summary: Remote datalogger
+      summary: Create DSMR reading by telegram
       description: |
         This allows you to insert a raw telegram into the application, as if it was read locally using the serial cable.
 
+        ### Script
         You can use a script to run in Supervisor. It will send telegrams to one or multiple instances of DSMR-reader.
         For detailed installation instructions, see [the installation guide for datalogger only](https://dsmr-reader.readthedocs.io/en/latest/installation/datalogger.html).
 
+        ### Note
+        It's difficult to create a valid URL encoded example. See the ``Python`` request sample for a better example of how to use this endpoint.
       requestBody:
         content:
           application/x-www-form-urlencoded:
@@ -62,33 +59,6 @@ paths:
                 telegram:
                   type: string
                   description: The raw telegram string containing all linefeeds ``\n``, and carriage returns ``\r``, as well!
-            examples:
-              1:
-                value:
-                  telegram: |
-                    /KFM5KAIFA-METER\r\n
-                    \r\n
-                    1-3:0.2.8(42)\r\n
-                    0-0:1.0.0(160303164347W)\r\n
-                    0-0:96.1.1(*******************************)\r\n
-                    1-0:1.8.1(001073.079*kWh)\r\n
-                    1-0:1.8.2(001263.199*kWh)\r\n
-                    1-0:2.8.1(000000.000*kWh)\r\n
-                    1-0:2.8.2(000000.000*kWh)\r\n
-                    0-0:96.14.0(0002)\r\n
-                    1-0:1.7.0(00.143*kW)\r\n
-                    1-0:2.7.0(00.000*kW)\r\n
-                    0-0:96.7.21(00006)\r\n
-                    0-0:96.7.9(00003)\r\n
-                    1-0:99.97.0(1)(0-0:96.7.19)(000101000001W)(2147483647*s)\r\n
-                    1-0:32.32.0(00000)\r\n
-                    1-0:32.36.0(00000)\r\n
-                    0-0:96.13.1()\r\n
-                    0-0:96.13.0()\r\n
-                    1-0:31.7.0(000*A)\r\n
-                    1-0:21.7.0(00.143*kW)\r\n
-                    1-0:22.7.0(00.000*kW)\r\n
-                    !74B0\n
       x-code-samples:
         - lang: 'Python'
           source: |
@@ -466,6 +436,7 @@ paths:
         *This endpoint was added in DSMR-reader ``v3.1.0``*
 
         ### All parameters are optional
+        *As this is a ``PATCH`` operation, you can specify one, multiple of all parameters fields, depending on your own needs.*
       requestBody:
         content:
           application/x-www-form-urlencoded: