From f301c759c3bb128376c538401d0712d7a1b975ae Mon Sep 17 00:00:00 2001
From: Jan Eitzinger <jan@moebiusband.org>
Date: Wed, 23 Oct 2024 16:13:20 +0200
Subject: [PATCH] Update and extend REST API descriptions

---
 api/swagger.json     |  5 +++--
 api/swagger.yaml     |  5 +++--
 internal/api/api.go  | 16 +++++++++++-----
 internal/api/docs.go |  5 +++--
 4 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/api/swagger.json b/api/swagger.json
index 08522ca..9024d5c 100644
--- a/api/swagger.json
+++ b/api/swagger.json
@@ -24,7 +24,7 @@
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Write metrics to store",
+                "description": "This endpoint allows the users to print the content of",
                 "produces": [
                     "application/json"
                 ],
@@ -81,6 +81,7 @@
                         "ApiKeyAuth": []
                     }
                 ],
+                "description": "This endpoint allows the users to free the Buffers from the",
                 "produces": [
                     "application/json"
                 ],
@@ -136,7 +137,7 @@
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Query metrics.",
+                "description": "This endpoint allows the users to retrieve data from the",
                 "consumes": [
                     "application/json"
                 ],
diff --git a/api/swagger.yaml b/api/swagger.yaml
index b14ba8a..a06e2f7 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -106,7 +106,7 @@ info:
 paths:
   /debug/:
     post:
-      description: Write metrics to store
+      description: This endpoint allows the users to print the content of
       parameters:
       - description: Selector
         in: query
@@ -142,6 +142,7 @@ paths:
       - debug
   /free/:
     post:
+      description: This endpoint allows the users to free the Buffers from the
       parameters:
       - description: up to timestamp
         in: query
@@ -178,7 +179,7 @@ paths:
     get:
       consumes:
       - application/json
-      description: Query metrics.
+      description: This endpoint allows the users to retrieve data from the
       parameters:
       - description: API query payload object
         in: body
diff --git a/internal/api/api.go b/internal/api/api.go
index 6e5968c..802b558 100644
--- a/internal/api/api.go
+++ b/internal/api/api.go
@@ -127,7 +127,10 @@ func (data *ApiMetricData) PadDataWithNull(ms *memorystore.MemoryStore, from, to
 // handleFree godoc
 // @summary
 // @tags free
-// @description
+// @description This endpoint allows the users to free the Buffers from the
+// metric store. This endpoint offers the users to remove then systematically
+// and also allows then to prune the data under node, if they do not want to
+// remove the whole node.
 // @produce     json
 // @param       to        query    string        false  "up to timestamp"
 // @success     200            {string} string  "ok"
@@ -182,9 +185,9 @@ func handleFree(rw http.ResponseWriter, r *http.Request) {
 }
 
 // handleWrite godoc
-// @summary Receive metrics in line-protocol
+// @summary Receive metrics in InfluxDB line-protocol
 // @tags write
-// @description Receives metrics in the influx line-protocol using [this format](https://github.com/ClusterCockpit/cc-specifications/blob/master/metrics/lineprotocol_alternative.md)
+// @description Write data to the in-memory store in the InfluxDB line-protocol using [this format](https://github.com/ClusterCockpit/cc-specifications/blob/master/metrics/lineprotocol_alternative.md)
 
 // @accept      plain
 // @produce     json
@@ -245,7 +248,9 @@ type ApiQuery struct {
 // handleQuery godoc
 // @summary    Query metrics
 // @tags query
-// @description Query metrics.
+// @description This endpoint allows the users to retrieve data from the
+// in-memory database. The CCMS will return data in JSON format for the
+// specified interval requested by the user
 // @accept      json
 // @produce     json
 // @param       request body     api.ApiQueryRequest  true "API query payload object"
@@ -383,7 +388,8 @@ func handleQuery(rw http.ResponseWriter, r *http.Request) {
 // handleDebug godoc
 // @summary Debug endpoint
 // @tags debug
-// @description Write metrics to store
+// @description This endpoint allows the users to print the content of
+// nodes/clusters/metrics to review the state of the data.
 // @produce     json
 // @param       selector        query    string            false "Selector"
 // @success     200            {string} string  "Debug dump"
diff --git a/internal/api/docs.go b/internal/api/docs.go
index 84cec70..e290e0b 100644
--- a/internal/api/docs.go
+++ b/internal/api/docs.go
@@ -30,7 +30,7 @@ const docTemplate = `{
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Write metrics to store",
+                "description": "This endpoint allows the users to print the content of",
                 "produces": [
                     "application/json"
                 ],
@@ -87,6 +87,7 @@ const docTemplate = `{
                         "ApiKeyAuth": []
                     }
                 ],
+                "description": "This endpoint allows the users to free the Buffers from the",
                 "produces": [
                     "application/json"
                 ],
@@ -142,7 +143,7 @@ const docTemplate = `{
                         "ApiKeyAuth": []
                     }
                 ],
-                "description": "Query metrics.",
+                "description": "This endpoint allows the users to retrieve data from the",
                 "consumes": [
                     "application/json"
                 ],