[api] update API docs and comments

cmd/sms-gateway/main.go

@@ -5,12 +5,18 @@ import (
 )
 
 //	@securitydefinitions.basic	ApiAuth
+//	@description				User authentication
 
 //	@securitydefinitions.apikey	MobileToken
 //	@in							header
 //	@name						Authorization
 //	@description				Mobile device token
 
+//	@securitydefinitions.apikey	ServerKey
+//	@in							header
+//	@name						Authorization
+//	@description				Private server authentication
+
 //	@title			SMS Gateway for Android™ API
 //	@version		{APP_VERSION}
 //	@description	This API provides programmatic access to sending SMS messages on Android devices. Features include sending SMS, checking message status, device management, webhook configuration, and system health checks.

internal/sms-gateway/handlers/mobile.go

@@ -53,7 +53,9 @@ func (h *mobileHandler) getDevice(device models.Device, c *fiber.Ctx) error {
 }
 
 //	@Summary		Register device
-//	@Description	Registers new device and returns credentials
+//	@Description	Registers new device for new or existing user. Returns user credentials only for new users
+//	@Security		ApiAuth
+//	@Security		ServerKey
 //	@Tags			Device
 //	@Accept			json
 //	@Produce		json
@@ -227,9 +229,10 @@ func (h *mobileHandler) Register(router fiber.Router) {
 		userauth.New(h.authSvc),
 		keyauth.New(keyauth.Config{
 			Next: func(c *fiber.Ctx) bool {
-				// skip server key authorization...
-				return h.authSvc.IsPublic() || // ...if public mode
-					userauth.HasUser(c) // ...if registration with existing user
+				// Skip server key authorization in the following cases:
+				// 1. Public mode is enabled - allowing open registration
+				// 2. User is already authenticated - allowing device registration for existing users
+				return h.authSvc.IsPublic() || userauth.HasUser(c)
 			},
 			Validator: func(c *fiber.Ctx, token string) (bool, error) {
 				err := h.authSvc.AuthorizeRegistration(token)

pkg/swagger/docs/swagger.json

@@ -506,7 +506,15 @@
                 }
             },
             "post": {
-                "description": "Registers new device and returns credentials",
+                "security": [
+                    {
+                        "ApiAuth": []
+                    },
+                    {
+                        "ServerKey": []
+                    }
+                ],
+                "description": "Registers new device for new or existing user. Returns user credentials only for new users",
                 "consumes": [
                     "application/json"
                 ],
@@ -1412,6 +1420,12 @@
             "type": "apiKey",
             "name": "Authorization",
             "in": "header"
+        },
+        "ServerKey": {
+            "description": "Private server authentication",
+            "type": "apiKey",
+            "name": "Authorization",
+            "in": "header"
         }
     }
 }

pkg/swagger/docs/swagger.yaml

@@ -777,7 +777,8 @@ paths:
     post:
       consumes:
       - application/json
-      description: Registers new device and returns credentials
+      description: Registers new device for new or existing user. Returns user credentials
+        only for new users
       parameters:
       - description: Device registration request
         in: body
@@ -808,6 +809,9 @@ paths:
           description: Internal server error
           schema:
             $ref: '#/definitions/smsgateway.ErrorResponse'
+      security:
+      - ApiAuth: []
+      - ServerKey: []
       summary: Register device
       tags:
       - Device
@@ -971,4 +975,9 @@ securityDefinitions:
     in: header
     name: Authorization
     type: apiKey
+  ServerKey:
+    description: Private server authentication
+    in: header
+    name: Authorization
+    type: apiKey
 swagger: "2.0"