From c2899fd727b7c03bd87c9eb70da5285d4df30fda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Schw=C3=B6rer?= Date: Sun, 20 Nov 2022 13:18:09 +0100 Subject: [PATCH] swagger doku for compat methods --- server/README.md | 2 - server/api/handler/compat.go | 77 +++++++++++--- server/swagger/swagger.json | 191 +++++++++++++++++++++++++++++++---- server/swagger/swagger.yaml | 134 +++++++++++++++++++++--- 4 files changed, 357 insertions(+), 47 deletions(-) diff --git a/server/README.md b/server/README.md index 1087a8a..6f39202 100644 --- a/server/README.md +++ b/server/README.md @@ -8,8 +8,6 @@ - https://firebase.google.com/docs/cloud-messaging/send-message#rest - List subscriptions on all owned channels (RESTful?) - deploy - - Dockerfile - - php in html - full-text-search: https://www.sqlite.org/fts5.html#contentless_tables - route to re-create keys - ack/read deliveries && return ack-count diff --git a/server/api/handler/compat.go b/server/api/handler/compat.go index 1bd8d33..93092f9 100644 --- a/server/api/handler/compat.go +++ b/server/api/handler/compat.go @@ -29,17 +29,24 @@ func NewCompatHandler(app *logic.Application) CompatHandler { // @Summary Register a new account // @ID compat-register // @Deprecated +// // @Param fcm_token query string true "the (android) fcm token" // @Param pro query string true "if the user is a paid account" Enums(true, false) // @Param pro_token query string true "the (android) IAP token" +// +// @Param fcm_token formData string true "the (android) fcm token" +// @Param pro formData string true "if the user is a paid account" Enums(true, false) +// @Param pro_token formData string true "the (android) IAP token" +// // @Success 200 {object} handler.Register.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/register.php [get] func (h CompatHandler) Register(g *gin.Context) ginresp.HTTPResponse { type query struct { - FCMToken *string `form:"fcm_token" json:"fcm_token"` - Pro *string `form:"pro" json:"pro"` - ProToken *string `form:"pro_token" json:"pro_token"` + FCMToken *string `form:"fcm_token"` + Pro *string `form:"pro"` + ProToken *string `form:"pro_token"` } type response struct { Success bool `json:"success"` @@ -53,7 +60,7 @@ func (h CompatHandler) Register(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -128,10 +135,16 @@ func (h CompatHandler) Register(g *gin.Context) ginresp.HTTPResponse { // @Summary Get information about the current user // @ID compat-info // @Deprecated +// // @Param user_id query string true "the user_id" // @Param user_key query string true "the user_key" +// +// @Param user_id formData string true "the user_id" +// @Param user_key formData string true "the user_key" +// // @Success 200 {object} handler.Info.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/info.php [get] func (h CompatHandler) Info(g *gin.Context) ginresp.HTTPResponse { type query struct { @@ -152,7 +165,7 @@ func (h CompatHandler) Info(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -204,11 +217,18 @@ func (h CompatHandler) Info(g *gin.Context) ginresp.HTTPResponse { // @Summary Acknowledge that a message was received // @ID compat-ack // @Deprecated +// // @Param user_id query string true "the user_id" // @Param user_key query string true "the user_key" // @Param scn_msg_id query string true "the message id" +// +// @Param user_id formData string true "the user_id" +// @Param user_key formData string true "the user_key" +// @Param scn_msg_id formData string true "the message id" +// // @Success 200 {object} handler.Ack.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/ack.php [get] func (h CompatHandler) Ack(g *gin.Context) ginresp.HTTPResponse { type query struct { @@ -225,7 +245,7 @@ func (h CompatHandler) Ack(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -268,10 +288,16 @@ func (h CompatHandler) Ack(g *gin.Context) ginresp.HTTPResponse { // @Summary Return all not-acknowledged messages // @ID compat-requery // @Deprecated +// // @Param user_id query string true "the user_id" // @Param user_key query string true "the user_key" +// +// @Param user_id formData string true "the user_id" +// @Param user_key formData string true "the user_key" +// // @Success 200 {object} handler.Requery.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/requery.php [get] func (h CompatHandler) Requery(g *gin.Context) ginresp.HTTPResponse { type query struct { @@ -287,7 +313,7 @@ func (h CompatHandler) Requery(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -327,11 +353,18 @@ func (h CompatHandler) Requery(g *gin.Context) ginresp.HTTPResponse { // @Summary Set the fcm-token (android) // @ID compat-update // @Deprecated +// // @Param user_id query string true "the user_id" // @Param user_key query string true "the user_key" // @Param fcm_token query string true "the (android) fcm token" +// +// @Param user_id formData string true "the user_id" +// @Param user_key formData string true "the user_key" +// @Param fcm_token formData string true "the (android) fcm token" +// // @Success 200 {object} handler.Update.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/update.php [get] func (h CompatHandler) Update(g *gin.Context) ginresp.HTTPResponse { type query struct { @@ -351,7 +384,7 @@ func (h CompatHandler) Update(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -431,8 +464,18 @@ func (h CompatHandler) Update(g *gin.Context) ginresp.HTTPResponse { // @Summary Get a whole (potentially truncated) message // @ID compat-expand // @Deprecated -// @Success 200 {object} handler.Expand.response -// @Failure 200 {object} ginresp.compatAPIError +// +// @Param user_id query string true "The user_id" +// @Param user_key query string true "The user_key" +// @Param scn_msg_id query string true "The message-id" +// +// @Param user_id formData string true "The user_id" +// @Param user_key formData string true "The user_key" +// @Param scn_msg_id formData string true "The message-id" +// +// @Success 200 {object} handler.Expand.response +// @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/expand.php [get] func (h CompatHandler) Expand(g *gin.Context) ginresp.HTTPResponse { type query struct { @@ -448,7 +491,7 @@ func (h CompatHandler) Expand(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } @@ -505,14 +548,22 @@ func (h CompatHandler) Expand(g *gin.Context) ginresp.HTTPResponse { // // @Summary Upgrade a free account to a paid account // @ID compat-upgrade +// @Deprecated +// // @Param user_id query string true "the user_id" // @Param user_key query string true "the user_key" // @Param pro query string true "if the user is a paid account" Enums(true, false) // @Param pro_token query string true "the (android) IAP token" +// +// @Param user_id formData string true "the user_id" +// @Param user_key formData string true "the user_key" +// @Param pro formData string true "if the user is a paid account" Enums(true, false) +// @Param pro_token formData string true "the (android) IAP token" +// // @Success 200 {object} handler.Upgrade.response // @Failure 200 {object} ginresp.compatAPIError +// // @Router /api/upgrade.php [get] -// @Deprecated func (h CompatHandler) Upgrade(g *gin.Context) ginresp.HTTPResponse { type query struct { UserID *int64 `form:"user_id"` @@ -531,7 +582,7 @@ func (h CompatHandler) Upgrade(g *gin.Context) ginresp.HTTPResponse { var datq query var datb query - ctx, errResp := h.app.StartRequest(g, nil, &datq, &datb, nil) + ctx, errResp := h.app.StartRequest(g, nil, &datq, nil, &datb) if errResp != nil { return *errResp } diff --git a/server/swagger/swagger.json b/server/swagger/swagger.json index ff76729..f0ed843 100644 --- a/server/swagger/swagger.json +++ b/server/swagger/swagger.json @@ -1005,6 +1005,27 @@ "name": "scn_msg_id", "in": "query", "required": true + }, + { + "type": "string", + "description": "the user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the user_key", + "name": "user_key", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the message id", + "name": "scn_msg_id", + "in": "formData", + "required": true } ], "responses": { @@ -1022,6 +1043,50 @@ "summary": "Get a whole (potentially truncated) message", "operationId": "compat-expand", "deprecated": true, + "parameters": [ + { + "type": "string", + "description": "The user_id", + "name": "user_id", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "The user_key", + "name": "user_key", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "The message-id", + "name": "scn_msg_id", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "The user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "The user_key", + "name": "user_key", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "The message-id", + "name": "scn_msg_id", + "in": "formData", + "required": true + } + ], "responses": { "200": { "description": "OK", @@ -1051,6 +1116,20 @@ "name": "user_key", "in": "query", "required": true + }, + { + "type": "string", + "description": "the user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the user_key", + "name": "user_key", + "in": "formData", + "required": true } ], "responses": { @@ -1093,6 +1172,31 @@ "name": "pro_token", "in": "query", "required": true + }, + { + "type": "string", + "description": "the (android) fcm token", + "name": "fcm_token", + "in": "formData", + "required": true + }, + { + "enum": [ + "true", + "false" + ], + "type": "string", + "description": "if the user is a paid account", + "name": "pro", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the (android) IAP token", + "name": "pro_token", + "in": "formData", + "required": true } ], "responses": { @@ -1124,6 +1228,20 @@ "name": "user_key", "in": "query", "required": true + }, + { + "type": "string", + "description": "the user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the user_key", + "name": "user_key", + "in": "formData", + "required": true } ], "responses": { @@ -1162,6 +1280,27 @@ "name": "fcm_token", "in": "query", "required": true + }, + { + "type": "string", + "description": "the user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the user_key", + "name": "user_key", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the (android) fcm token", + "name": "fcm_token", + "in": "formData", + "required": true } ], "responses": { @@ -1211,6 +1350,38 @@ "name": "pro_token", "in": "query", "required": true + }, + { + "type": "string", + "description": "the user_id", + "name": "user_id", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the user_key", + "name": "user_key", + "in": "formData", + "required": true + }, + { + "enum": [ + "true", + "false" + ], + "type": "string", + "description": "if the user is a paid account", + "name": "pro", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "the (android) IAP token", + "name": "pro_token", + "in": "formData", + "required": true } ], "responses": { @@ -1446,16 +1617,6 @@ "summary": "Send a new message (compatibility)", "deprecated": true, "parameters": [ - { - "type": "string", - "name": "chanKey", - "in": "query" - }, - { - "type": "string", - "name": "channel", - "in": "query" - }, { "type": "string", "name": "content", @@ -1491,16 +1652,6 @@ "name": "userMessageID", "in": "query" }, - { - "type": "string", - "name": "chanKey", - "in": "formData" - }, - { - "type": "string", - "name": "channel", - "in": "formData" - }, { "type": "string", "name": "content", diff --git a/server/swagger/swagger.yaml b/server/swagger/swagger.yaml index 4651dfd..a289464 100644 --- a/server/swagger/swagger.yaml +++ b/server/swagger/swagger.yaml @@ -1110,6 +1110,21 @@ paths: name: scn_msg_id required: true type: string + - description: the user_id + in: formData + name: user_id + required: true + type: string + - description: the user_key + in: formData + name: user_key + required: true + type: string + - description: the message id + in: formData + name: scn_msg_id + required: true + type: string responses: "200": description: OK @@ -1120,6 +1135,37 @@ paths: get: deprecated: true operationId: compat-expand + parameters: + - description: The user_id + in: query + name: user_id + required: true + type: string + - description: The user_key + in: query + name: user_key + required: true + type: string + - description: The message-id + in: query + name: scn_msg_id + required: true + type: string + - description: The user_id + in: formData + name: user_id + required: true + type: string + - description: The user_key + in: formData + name: user_key + required: true + type: string + - description: The message-id + in: formData + name: scn_msg_id + required: true + type: string responses: "200": description: OK @@ -1141,6 +1187,16 @@ paths: name: user_key required: true type: string + - description: the user_id + in: formData + name: user_id + required: true + type: string + - description: the user_key + in: formData + name: user_key + required: true + type: string responses: "200": description: OK @@ -1170,6 +1226,24 @@ paths: name: pro_token required: true type: string + - description: the (android) fcm token + in: formData + name: fcm_token + required: true + type: string + - description: if the user is a paid account + enum: + - "true" + - "false" + in: formData + name: pro + required: true + type: string + - description: the (android) IAP token + in: formData + name: pro_token + required: true + type: string responses: "200": description: OK @@ -1191,6 +1265,16 @@ paths: name: user_key required: true type: string + - description: the user_id + in: formData + name: user_id + required: true + type: string + - description: the user_key + in: formData + name: user_key + required: true + type: string responses: "200": description: OK @@ -1217,6 +1301,21 @@ paths: name: fcm_token required: true type: string + - description: the user_id + in: formData + name: user_id + required: true + type: string + - description: the user_key + in: formData + name: user_key + required: true + type: string + - description: the (android) fcm token + in: formData + name: fcm_token + required: true + type: string responses: "200": description: OK @@ -1251,6 +1350,29 @@ paths: name: pro_token required: true type: string + - description: the user_id + in: formData + name: user_id + required: true + type: string + - description: the user_key + in: formData + name: user_key + required: true + type: string + - description: if the user is a paid account + enum: + - "true" + - "false" + in: formData + name: pro + required: true + type: string + - description: the (android) IAP token + in: formData + name: pro_token + required: true + type: string responses: "200": description: OK @@ -1399,12 +1521,6 @@ paths: description: All parameter can be set via query-parameter or form-data body. Only UserID, UserKey and Title are required parameters: - - in: query - name: chanKey - type: string - - in: query - name: channel - type: string - in: query name: content type: string @@ -1426,12 +1542,6 @@ paths: - in: query name: userMessageID type: string - - in: formData - name: chanKey - type: string - - in: formData - name: channel - type: string - in: formData name: content type: string