cleanup swagger

server/api/handler/api.go

@@ -430,7 +430,7 @@ func (h APIHandler) AddClient(g *gin.Context) ginresp.HTTPResponse {
 // @Failure 404 {object} ginresp.apiError
 // @Failure 500 {object} ginresp.apiError
 //
-// @Router  /api/users/{uid}/clients [POST]
+// @Router  /api/users/{uid}/clients [DELETE]
 func (h APIHandler) DeleteClient(g *gin.Context) ginresp.HTTPResponse {
 	type uri struct {
 		UserID   models.UserID   `uri:"uid"`
@@ -680,6 +680,8 @@ func (h APIHandler) UpdateChannel(g *gin.Context) ginresp.HTTPResponse {
 // @Tags        API-v2
 //
 // @Param       query_data query    handler.ListChannelMessages.query false " "
+// @Param       uid        path     int true "UserID"
+// @Param       cid        path     int true "ChannelID"
 //
 // @Success     200        {object} handler.ListChannelMessages.response
 // @Failure     400        {object} ginresp.apiError
@@ -1252,7 +1254,7 @@ func (h APIHandler) GetMessage(g *gin.Context) ginresp.HTTPResponse {
 // @Failure     404 {object} ginresp.apiError
 // @Failure     500 {object} ginresp.apiError
 //
-// @Router      /api/messages/{mid} [PATCH]
+// @Router      /api/messages/{mid} [DELETE]
 func (h APIHandler) DeleteMessage(g *gin.Context) ginresp.HTTPResponse {
 	type uri struct {
 		MessageID models.SCNMessageID `uri:"mid"`

server/api/handler/common.go

@@ -38,7 +38,6 @@ type pingResponseInfo struct {
 // Ping swaggerdoc
 //
 // @Summary Simple endpoint to test connection (any http method)
-// @ID      api-common-ping
 // @Tags    Common
 //
 // @Success 200 {object} pingResponse
@@ -134,6 +133,8 @@ func (h CommonHandler) Health(g *gin.Context) ginresp.HTTPResponse {
 // @ID      api-common-sleep
 // @Tags    Common
 //
+// @Param   secs path     number true "sleep delay (in seconds)"
+//
 // @Success 200 {object} handler.Sleep.response
 // @Failure 400 {object} ginresp.apiError
 // @Failure 500 {object} ginresp.apiError

server/swagger/swagger.json

@@ -510,7 +510,7 @@
             }
         },
         "/api/messages/{mid}": {
-            "patch": {
+            "delete": {
                 "description": "The user must own the message and request the resource with the ADMIN Key",
                 "tags": [
                     "API-v2"
@@ -558,6 +558,55 @@
                         }
                     }
                 }
+            },
+            "patch": {
+                "description": "The user must either own the message and request the resource with the READ or ADMIN Key\nOr the user must subscribe to the corresponding channel (and be confirmed) and request the resource with the READ or ADMIN Key\nThe returned message is never trimmed",
+                "tags": [
+                    "API-v2"
+                ],
+                "summary": "Get a single message (untrimmed)",
+                "operationId": "api-messages-get",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "SCNMessageID",
+                        "name": "mid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.MessageJSON"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    }
+                }
             }
         },
         "/api/ping": {
@@ -566,7 +615,6 @@
                     "Common"
                 ],
                 "summary": "Simple endpoint to test connection (any http method)",
-                "operationId": "api-common-ping",
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -587,7 +635,6 @@
                     "Common"
                 ],
                 "summary": "Simple endpoint to test connection (any http method)",
-                "operationId": "api-common-ping",
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -608,7 +655,6 @@
                     "Common"
                 ],
                 "summary": "Simple endpoint to test connection (any http method)",
-                "operationId": "api-common-ping",
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -629,7 +675,6 @@
                     "Common"
                 ],
                 "summary": "Simple endpoint to test connection (any http method)",
-                "operationId": "api-common-ping",
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -650,7 +695,6 @@
                     "Common"
                 ],
                 "summary": "Simple endpoint to test connection (any http method)",
-                "operationId": "api-common-ping",
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -792,6 +836,15 @@
                 ],
                 "summary": "Return 200 after x seconds",
                 "operationId": "api-common-sleep",
+                "parameters": [
+                    {
+                        "type": "number",
+                        "description": "sleep delay (in seconds)",
+                        "name": "secs",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
                 "responses": {
                     "200": {
                         "description": "OK",
@@ -1359,6 +1412,20 @@
                         "type": "boolean",
                         "name": "trimmed",
                         "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "UserID",
+                        "name": "uid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "description": "ChannelID",
+                        "name": "cid",
+                        "in": "path",
+                        "required": true
                     }
                 ],
                 "responses": {
@@ -1502,6 +1569,62 @@
                 }
             },
             "post": {
+                "tags": [
+                    "API-v2"
+                ],
+                "summary": "Add a new clients",
+                "operationId": "api-clients-create",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "UserID",
+                        "name": "uid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": " ",
+                        "name": "post_body",
+                        "in": "body",
+                        "schema": {
+                            "$ref": "#/definitions/handler.AddClient.body"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.ClientJSON"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/ginresp.apiError"
+                        }
+                    }
+                }
+            },
+            "delete": {
                 "tags": [
                     "API-v2"
                 ],

server/swagger/swagger.yaml

@@ -784,7 +784,7 @@ paths:
       tags:
       - API-v2
   /api/messages/{mid}:
-    patch:
+    delete:
       description: The user must own the message and request the resource with the
         ADMIN Key
       operationId: api-messages-delete
@@ -818,9 +818,44 @@ paths:
       summary: Delete a single message
       tags:
       - API-v2
+    patch:
+      description: |-
+        The user must either own the message and request the resource with the READ or ADMIN Key
+        Or the user must subscribe to the corresponding channel (and be confirmed) and request the resource with the READ or ADMIN Key
+        The returned message is never trimmed
+      operationId: api-messages-get
+      parameters:
+      - description: SCNMessageID
+        in: path
+        name: mid
+        required: true
+        type: integer
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.MessageJSON'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+      summary: Get a single message (untrimmed)
+      tags:
+      - API-v2
   /api/ping:
     delete:
-      operationId: api-common-ping
       responses:
         "200":
           description: OK
@@ -834,7 +869,6 @@ paths:
       tags:
       - Common
     get:
-      operationId: api-common-ping
       responses:
         "200":
           description: OK
@@ -848,7 +882,6 @@ paths:
       tags:
       - Common
     patch:
-      operationId: api-common-ping
       responses:
         "200":
           description: OK
@@ -862,7 +895,6 @@ paths:
       tags:
       - Common
     post:
-      operationId: api-common-ping
       responses:
         "200":
           description: OK
@@ -876,7 +908,6 @@ paths:
       tags:
       - Common
     put:
-      operationId: api-common-ping
       responses:
         "200":
           description: OK
@@ -974,6 +1005,12 @@ paths:
   /api/sleep/{secs}:
     post:
       operationId: api-common-sleep
+      parameters:
+      - description: sleep delay (in seconds)
+        in: path
+        name: secs
+        required: true
+        type: number
       responses:
         "200":
           description: OK
@@ -1365,6 +1402,16 @@ paths:
       - in: query
         name: trimmed
         type: boolean
+      - description: UserID
+        in: path
+        name: uid
+        required: true
+        type: integer
+      - description: ChannelID
+        in: path
+        name: cid
+        required: true
+        type: integer
       responses:
         "200":
           description: OK
@@ -1428,39 +1475,7 @@ paths:
       tags:
       - API-v2
   /api/users/{uid}/clients:
-    get:
+    delete:
-      operationId: api-clients-list
-      parameters:
-      - description: UserID
-        in: path
-        name: uid
-        required: true
-        type: integer
-      responses:
-        "200":
-          description: OK
-          schema:
-            $ref: '#/definitions/handler.ListClients.response'
-        "400":
-          description: Bad Request
-          schema:
-            $ref: '#/definitions/ginresp.apiError'
-        "401":
-          description: Unauthorized
-          schema:
-            $ref: '#/definitions/ginresp.apiError'
-        "404":
-          description: Not Found
-          schema:
-            $ref: '#/definitions/ginresp.apiError'
-        "500":
-          description: Internal Server Error
-          schema:
-            $ref: '#/definitions/ginresp.apiError'
-      summary: List all clients
-      tags:
-      - API-v2
-    post:
       operationId: api-clients-delete
       parameters:
       - description: UserID
@@ -1497,6 +1512,75 @@ paths:
       summary: Delete a client
       tags:
       - API-v2
+    get:
+      operationId: api-clients-list
+      parameters:
+      - description: UserID
+        in: path
+        name: uid
+        required: true
+        type: integer
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/handler.ListClients.response'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+      summary: List all clients
+      tags:
+      - API-v2
+    post:
+      operationId: api-clients-create
+      parameters:
+      - description: UserID
+        in: path
+        name: uid
+        required: true
+        type: integer
+      - description: ' '
+        in: body
+        name: post_body
+        schema:
+          $ref: '#/definitions/handler.AddClient.body'
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.ClientJSON'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/ginresp.apiError'
+      summary: Add a new clients
+      tags:
+      - API-v2
   /api/users/{uid}/clients/{cid}:
     get:
       operationId: api-clients-get