[docs] minor improvements to the API docs

Author: capcom6

internal/sms-gateway/handlers/messages/3rdparty.go

@@ -40,21 +40,21 @@ type ThirdPartyController struct {
 }
 
 //	@Summary		Enqueue message
-//	@Description	Enqueues message for sending. If multiple devices are registered, it will be sent via a random one
+//	@Description	Enqueues a message for sending. If `deviceId` is set, the specified device is used; otherwise a random registered device is chosen.
 //	@Security		ApiAuth
 //	@Tags			User, Messages
 //	@Accept			json
 //	@Produce		json
 //	@Param			skipPhoneValidation		query		bool							false	"Skip phone validation"
-//	@Param			deviceActiveWithin		query		int								false	"Filter devices active within the specified number of hours"	default(0)
+//	@Param			deviceActiveWithin		query		int								false	"Filter devices active within the specified number of hours"	default(0)	minimum(0)
 //	@Param			request					body		smsgateway.Message				true	"Send message request"
 //	@Success		202						{object}	smsgateway.GetMessageResponse	"Message enqueued"
 //	@Failure		400						{object}	smsgateway.ErrorResponse		"Invalid request"
 //	@Failure		401						{object}	smsgateway.ErrorResponse		"Unauthorized"
 //	@Failure		409						{object}	smsgateway.ErrorResponse		"Message with such ID already exists"
 //	@Failure		500						{object}	smsgateway.ErrorResponse		"Internal server error"
 //	@Header			202						{string}	Location						"Get message state URL"
-//	@Router			/3rdparty/v1/messages 																													[post]
+//	@Router			/3rdparty/v1/messages 																																																																	[post]
 //
 // Enqueue message
 func (h *ThirdPartyController) post(user models.User, c *fiber.Ctx) error {
@@ -179,7 +179,7 @@ func (h *ThirdPartyController) post(user models.User, c *fiber.Ctx) error {
 //	@Failure		400							{object}	smsgateway.ErrorResponse		"Invalid request"
 //	@Failure		401							{object}	smsgateway.ErrorResponse		"Unauthorized"
 //	@Failure		500							{object}	smsgateway.ErrorResponse		"Internal server error"
-//	@Router			/3rdparty/v1/messages/{id} 																												[get]
+//	@Router			/3rdparty/v1/messages/{id} 																																																																[get]
 //
 // Get message state
 func (h *ThirdPartyController) get(user models.User, c *fiber.Ctx) error {
@@ -216,7 +216,7 @@ func (h *ThirdPartyController) get(user models.User, c *fiber.Ctx) error {
 //	@Failure		400							{object}	smsgateway.ErrorResponse			"Invalid request"
 //	@Failure		401							{object}	smsgateway.ErrorResponse			"Unauthorized"
 //	@Failure		500							{object}	smsgateway.ErrorResponse			"Internal server error"
-//	@Router			/3rdparty/v1/inbox/export 																																		[post]
+//	@Router			/3rdparty/v1/inbox/export 																																																																										[post]
 //
 // Export inbox
 func (h *ThirdPartyController) postInboxExport(user models.User, c *fiber.Ctx) error {

internal/sms-gateway/handlers/mobile.go

@@ -195,12 +195,13 @@ func (h *mobileHandler) patchMessage(device models.Device, c *fiber.Ctx) error {
 		return fiber.NewError(fiber.StatusBadRequest, err.Error())
 	}
 
-	var messageState messages.MessageStateIn
 	for _, v := range req {
-		messageState.ID = v.ID
-		messageState.State = messages.ProcessingState(v.State)
-		messageState.Recipients = v.Recipients
-		messageState.States = v.States
+		messageState := messages.MessageStateIn{
+			ID:         v.ID,
+			State:      messages.ProcessingState(v.State),
+			Recipients: v.Recipients,
+			States:     v.States,
+		}
 
 		err := h.messagesSvc.UpdateState(device.ID, messageState)
 		if err != nil && !errors.Is(err, messages.ErrMessageNotFound) {

pkg/swagger/docs/swagger.json

@@ -271,7 +271,7 @@
                         "ApiAuth": []
                     }
                 ],
-                "description": "Enqueues message for sending. If multiple devices are registered, it will be sent via a random one",
+                "description": "Enqueues a message for sending. If `deviceId` is set, the specified device is used; otherwise a random registered device is chosen.",
                 "consumes": [
                     "application/json"
                 ],
@@ -291,6 +291,7 @@
                         "in": "query"
                     },
                     {
+                        "minimum": 0,
                         "type": "integer",
                         "default": 0,
                         "description": "Filter devices active within the specified number of hours",

pkg/swagger/docs/swagger.yaml

@@ -893,8 +893,8 @@ paths:
     post:
       consumes:
       - application/json
-      description: Enqueues message for sending. If multiple devices are registered,
-        it will be sent via a random one
+      description: Enqueues a message for sending. If `deviceId` is set, the specified
+        device is used; otherwise a random registered device is chosen.
       parameters:
       - description: Skip phone validation
         in: query
@@ -903,6 +903,7 @@ paths:
       - default: 0
         description: Filter devices active within the specified number of hours
         in: query
+        minimum: 0
         name: deviceActiveWithin
         type: integer
       - description: Send message request