From 37e09d65321f32ab119ff3d07a7eeb5d5405a668 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Schw=C3=B6rer?= Date: Wed, 23 Nov 2022 22:12:47 +0100 Subject: [PATCH] cleanup swagger --- server/api/handler/api.go | 6 +- server/api/handler/common.go | 3 +- server/swagger/swagger.json | 135 +++++++++++++++++++++++++++-- server/swagger/swagger.yaml | 162 ++++++++++++++++++++++++++--------- 4 files changed, 258 insertions(+), 48 deletions(-) diff --git a/server/api/handler/api.go b/server/api/handler/api.go index 5179907..9b61265 100644 --- a/server/api/handler/api.go +++ b/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"` diff --git a/server/api/handler/common.go b/server/api/handler/common.go index d4ac9a3..13bd5f4 100644 --- a/server/api/handler/common.go +++ b/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 diff --git a/server/swagger/swagger.json b/server/swagger/swagger.json index 65f2aca..bd484de 100644 --- a/server/swagger/swagger.json +++ b/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" ], diff --git a/server/swagger/swagger.yaml b/server/swagger/swagger.yaml index cd7987b..b0ad1be 100644 --- a/server/swagger/swagger.yaml +++ b/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: - 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: + delete: 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