From 63b93fbe010e4178dd583447303f8c07d8df1ebc Mon Sep 17 00:00:00 2001 From: Aleksandr Soloshenko Date: Tue, 22 Jul 2025 14:42:43 +0700 Subject: [PATCH] [docs] update API docs --- .../sms-gateway/handlers/events/mobile.go | 16 +++ .../sms-gateway/handlers/messages/3rdparty.go | 44 +++---- internal/sms-gateway/handlers/mobile.go | 2 +- pkg/swagger/docs/swagger.json | 120 ++++++++++++------ pkg/swagger/docs/swagger.yaml | 83 ++++++++---- 5 files changed, 177 insertions(+), 88 deletions(-) diff --git a/internal/sms-gateway/handlers/events/mobile.go b/internal/sms-gateway/handlers/events/mobile.go index 4a70fb1..3df1661 100644 --- a/internal/sms-gateway/handlers/events/mobile.go +++ b/internal/sms-gateway/handlers/events/mobile.go @@ -26,6 +26,22 @@ func NewMobileController(sseService *sse.Service, validator *validator.Validate, } } +// @Summary Get events +// @Description Returns events stream for a device +// @Security MobileToken +// @Tags Device, Events +// @x-sse true +// @Produce text/event-stream +// @Header 200 {string} Content-Type "text/event-stream" +// @Header 200 {string} Transfer-Encoding "chunked" +// @Header 200 {string} Connection "keep-alive" +// @Header 200 {string} Cache-Control "no-cache" +// @Success 200 {string} string "Event" +// @Failure 401 {object} smsgateway.ErrorResponse "Unauthorized" +// @Failure 500 {object} smsgateway.ErrorResponse "Internal server error" +// @Router /mobile/v1/events [get] +// +// Get events func (h *MobileController) get(device models.Device, c *fiber.Ctx) error { return h.sseSvc.Handler(device.ID, c) } diff --git a/internal/sms-gateway/handlers/messages/3rdparty.go b/internal/sms-gateway/handlers/messages/3rdparty.go index 0374e5f..6610b2b 100644 --- a/internal/sms-gateway/handlers/messages/3rdparty.go +++ b/internal/sms-gateway/handlers/messages/3rdparty.go @@ -45,16 +45,16 @@ type ThirdPartyController struct { // @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) 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] +// @Param skipPhoneValidation query bool false "Skip phone validation" +// @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] // // Enqueue message func (h *ThirdPartyController) post(user models.User, c *fiber.Ctx) error { @@ -174,12 +174,12 @@ func (h *ThirdPartyController) post(user models.User, c *fiber.Ctx) error { // @Security ApiAuth // @Tags User, Messages // @Produce json -// @Param id path string true "Message ID" -// @Success 200 {object} smsgateway.GetMessageResponse "Message state" -// @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] +// @Param id path string true "Message ID" +// @Success 200 {object} smsgateway.GetMessageResponse "Message state" +// @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] // // Get message state func (h *ThirdPartyController) get(user models.User, c *fiber.Ctx) error { @@ -211,12 +211,12 @@ func (h *ThirdPartyController) get(user models.User, c *fiber.Ctx) error { // @Tags User, Messages // @Accept json // @Produce json -// @Param request body smsgateway.MessagesExportRequest true "Export inbox request" -// @Success 202 {object} object "Inbox export request accepted" -// @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] +// @Param request body smsgateway.MessagesExportRequest true "Export inbox request" +// @Success 202 {object} object "Inbox export request accepted" +// @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] // // Export inbox func (h *ThirdPartyController) postInboxExport(user models.User, c *fiber.Ctx) error { diff --git a/internal/sms-gateway/handlers/mobile.go b/internal/sms-gateway/handlers/mobile.go index f087b14..9480e20 100644 --- a/internal/sms-gateway/handlers/mobile.go +++ b/internal/sms-gateway/handlers/mobile.go @@ -184,7 +184,7 @@ func (h *mobileHandler) getMessage(device models.Device, c *fiber.Ctx) error { // @Tags Device, Messages // @Accept json // @Produce json -// @Param request body smsgateway.MobilePatchMessageRequest true "New message state" +// @Param request body smsgateway.MobilePatchMessageRequest true "List of message state updates" // @Success 204 {object} nil "Successfully updated" // @Failure 400 {object} smsgateway.ErrorResponse "Invalid request" // @Failure 500 {object} smsgateway.ErrorResponse "Internal server error" diff --git a/pkg/swagger/docs/swagger.json b/pkg/swagger/docs/swagger.json index 31836ea..7afe420 100644 --- a/pkg/swagger/docs/swagger.json +++ b/pkg/swagger/docs/swagger.json @@ -837,6 +837,45 @@ } } }, + "/mobile/v1/events": { + "get": { + "security": [ + { + "MobileToken": [] + } + ], + "description": "Returns events stream for a device", + "produces": [ + "text/event-stream" + ], + "tags": [ + "Device", + "Events" + ], + "summary": "Get events", + "responses": { + "200": { + "description": "Event", + "schema": { + "type": "string" + } + }, + "401": { + "description": "Unauthorized", + "schema": { + "$ref": "#/definitions/smsgateway.ErrorResponse" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "#/definitions/smsgateway.ErrorResponse" + } + } + }, + "x-sse": true + } + }, "/mobile/v1/message": { "get": { "security": [ @@ -894,50 +933,14 @@ "summary": "Update message state", "parameters": [ { - "description": "New message state", + "description": "List of message state updates", "name": "request", "in": "body", "required": true, "schema": { "type": "array", "items": { - "type": "object", - "required": [ - "recipients", - "state" - ], - "properties": { - "id": { - "description": "Message ID", - "type": "string", - "maxLength": 36, - "example": "PyDmBQZZXYmyxMwED8Fzy" - }, - "recipients": { - "description": "Recipients states", - "type": "array", - "minItems": 1, - "items": { - "$ref": "#/definitions/smsgateway.RecipientState" - } - }, - "state": { - "description": "State", - "allOf": [ - { - "$ref": "#/definitions/smsgateway.ProcessingState" - } - ], - "example": "Pending" - }, - "states": { - "description": "History of states", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - } + "$ref": "#/definitions/smsgateway.MobilePatchMessageItem" } } } @@ -1307,6 +1310,7 @@ "type": "object", "required": [ "deviceId", + "id", "recipients", "state" ], @@ -1770,6 +1774,46 @@ } } }, + "smsgateway.MobilePatchMessageItem": { + "type": "object", + "required": [ + "id", + "recipients", + "state" + ], + "properties": { + "id": { + "description": "Message ID", + "type": "string", + "maxLength": 36, + "example": "PyDmBQZZXYmyxMwED8Fzy" + }, + "recipients": { + "description": "Recipients states", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/smsgateway.RecipientState" + } + }, + "state": { + "description": "State", + "allOf": [ + { + "$ref": "#/definitions/smsgateway.ProcessingState" + } + ], + "example": "Pending" + }, + "states": { + "description": "History of states", + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, "smsgateway.MobileRegisterRequest": { "type": "object", "properties": { diff --git a/pkg/swagger/docs/swagger.yaml b/pkg/swagger/docs/swagger.yaml index 6d1b14b..b5d2a2d 100644 --- a/pkg/swagger/docs/swagger.yaml +++ b/pkg/swagger/docs/swagger.yaml @@ -118,6 +118,7 @@ definitions: type: object required: - deviceId + - id - recipients - state type: object @@ -428,6 +429,34 @@ definitions: required: - phoneNumbers type: object + smsgateway.MobilePatchMessageItem: + properties: + id: + description: Message ID + example: PyDmBQZZXYmyxMwED8Fzy + maxLength: 36 + type: string + recipients: + description: Recipients states + items: + $ref: '#/definitions/smsgateway.RecipientState' + minItems: 1 + type: array + state: + allOf: + - $ref: '#/definitions/smsgateway.ProcessingState' + description: State + example: Pending + states: + additionalProperties: + type: string + description: History of states + type: object + required: + - id + - recipients + - state + type: object smsgateway.MobileRegisterRequest: properties: name: @@ -1258,6 +1287,31 @@ paths: summary: Register device tags: - Device + /mobile/v1/events: + get: + description: Returns events stream for a device + produces: + - text/event-stream + responses: + "200": + description: Event + schema: + type: string + "401": + description: Unauthorized + schema: + $ref: '#/definitions/smsgateway.ErrorResponse' + "500": + description: Internal server error + schema: + $ref: '#/definitions/smsgateway.ErrorResponse' + security: + - MobileToken: [] + summary: Get events + tags: + - Device + - Events + x-sse: true /mobile/v1/message: get: consumes: @@ -1287,38 +1341,13 @@ paths: - application/json description: Updates message state parameters: - - description: New message state + - description: List of message state updates in: body name: request required: true schema: items: - properties: - id: - description: Message ID - example: PyDmBQZZXYmyxMwED8Fzy - maxLength: 36 - type: string - recipients: - description: Recipients states - items: - $ref: '#/definitions/smsgateway.RecipientState' - minItems: 1 - type: array - state: - allOf: - - $ref: '#/definitions/smsgateway.ProcessingState' - description: State - example: Pending - states: - additionalProperties: - type: string - description: History of states - type: object - required: - - recipients - - state - type: object + $ref: '#/definitions/smsgateway.MobilePatchMessageItem' type: array produces: - application/json