docs(server): Add explanation to configuration type

tum-esm · Jul 10, 2023 · 3adf6e4 · 3adf6e4
1 parent af1fc03
commit 3adf6e4
Showing 1 changed file with 13 additions and 6 deletions.
diff --git a/server/openapi.yml b/server/openapi.yml
@@ -207,7 +207,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
+              $ref: "#/components/schemas/configuration"
       responses:
         "201":
           description: Created
@@ -238,7 +238,7 @@ paths:
                   type: object
                   properties:
                     value:
-                      type: object
+                      $ref: "#/components/schemas/configuration"
                     revision:
                       $ref: "#/components/schemas/revision"
                     creation_timestamp:
@@ -358,6 +358,10 @@ components:
       type: string
       example: 575a7328-4e2e-4b88-afcc-e0b5ed3920cc
       pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+    token:
+      type: string
+      example: c59805ae394cceea937163877ca31375183650586137170a69652b6d8543e869
+      pattern: "^[0-9a-f]{64}$"
     timestamp:
       type: number
       example: 1683644500.3
@@ -371,10 +375,13 @@ components:
       example: "12345678"
       minLength: 8
       maxLength: 256
-    token:
-      type: string
-      example: c59805ae394cceea937163877ca31375183650586137170a69652b6d8543e869
-      pattern: "^[0-9a-f]{64}$"
+    configuration:
+      description: "Configurations are JSON objects that are relayed to the sensors over MQTT. Sensors are expected to validate the configurations they receive and respond with positive or negative acknowledgements."
+      type: object
+      example:
+        somewhere: 8.5
+        what: true
+        tomorrow: "value"
     revision:
       description: "Configurations are assigned monotonically increasing revision numbers. The revision is used as an identifier in the communication with the sensors and can clearly match configurations to measurements and logs."
       type: integer