From 3adf6e452b7e0e94e0ff9bd771c21da30bcf0c8f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20B=C3=B6hm?= <felix@felixboehm.dev>
Date: Mon, 10 Jul 2023 19:37:47 +0100
Subject: [PATCH] docs(server): Add explanation to configuration type

---
 server/openapi.yml | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/server/openapi.yml b/server/openapi.yml
index d5780bd8..317eca03 100644
--- 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