From 00ad7e136d5e89468f1ed071b36897c8d4ae9f89 Mon Sep 17 00:00:00 2001
From: "n.nakhostin" <n.nakhostin@ravanertebat.com>
Date: Wed, 17 Sep 2025 16:05:33 +0330
Subject: [PATCH] Enhance API Documentation for Notification Target Audience

- Added "target" field reference to the notification request and response structures in Swagger documentation, improving clarity for API consumers.
- Introduced "notification.TargetAudienceType" definition with enumerated values for target audience options, enhancing the API's usability and understanding.
- Updated related documentation files (YAML and JSON) to reflect these changes, ensuring consistency across all API documentation formats.
---
 cmd/web/docs/docs.go       | 29 +++++++++++++++++++++++++++++
 cmd/web/docs/swagger.json  | 29 +++++++++++++++++++++++++++++
 cmd/web/docs/swagger.yaml  | 24 ++++++++++++++++++++++++
 internal/assets/handler.go |  2 +-
 4 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/cmd/web/docs/docs.go b/cmd/web/docs/docs.go
index 4182825..9be3aae 100644
--- a/cmd/web/docs/docs.go
+++ b/cmd/web/docs/docs.go
@@ -7432,6 +7432,9 @@ const docTemplate = `{
                 "schedule": {
                     "$ref": "#/definitions/notification.ScheduleRequest"
                 },
+                "target": {
+                    "$ref": "#/definitions/notification.TargetAudienceType"
+                },
                 "tender": {
                     "type": "string"
                 },
@@ -7467,6 +7470,9 @@ const docTemplate = `{
                 "schedule": {
                     "$ref": "#/definitions/notification.ScheduleResponse"
                 },
+                "target": {
+                    "$ref": "#/definitions/notification.TargetAudienceType"
+                },
                 "tender": {
                     "type": "string"
                 },
@@ -7544,6 +7550,29 @@ const docTemplate = `{
                 }
             }
         },
+        "notification.TargetAudienceType": {
+            "type": "string",
+            "enum": [
+                "all_users",
+                "specific_users",
+                "all_role",
+                "specific_role",
+                "all_companies",
+                "specific_company",
+                "all_customers",
+                "specific_customer"
+            ],
+            "x-enum-varnames": [
+                "TargetAudienceAllUsers",
+                "TargetAudienceSpecificUsers",
+                "TargetAudienceAllRole",
+                "TargetAudienceSpecificRole",
+                "TargetAudienceAllCompanies",
+                "TargetAudienceSpecificCompany",
+                "TargetAudienceAllCustomers",
+                "TargetAudienceSpecificCustomer"
+            ]
+        },
         "response.APIError": {
             "type": "object",
             "properties": {
diff --git a/cmd/web/docs/swagger.json b/cmd/web/docs/swagger.json
index b24b641..f652c5f 100644
--- a/cmd/web/docs/swagger.json
+++ b/cmd/web/docs/swagger.json
@@ -7426,6 +7426,9 @@
                 "schedule": {
                     "$ref": "#/definitions/notification.ScheduleRequest"
                 },
+                "target": {
+                    "$ref": "#/definitions/notification.TargetAudienceType"
+                },
                 "tender": {
                     "type": "string"
                 },
@@ -7461,6 +7464,9 @@
                 "schedule": {
                     "$ref": "#/definitions/notification.ScheduleResponse"
                 },
+                "target": {
+                    "$ref": "#/definitions/notification.TargetAudienceType"
+                },
                 "tender": {
                     "type": "string"
                 },
@@ -7538,6 +7544,29 @@
                 }
             }
         },
+        "notification.TargetAudienceType": {
+            "type": "string",
+            "enum": [
+                "all_users",
+                "specific_users",
+                "all_role",
+                "specific_role",
+                "all_companies",
+                "specific_company",
+                "all_customers",
+                "specific_customer"
+            ],
+            "x-enum-varnames": [
+                "TargetAudienceAllUsers",
+                "TargetAudienceSpecificUsers",
+                "TargetAudienceAllRole",
+                "TargetAudienceSpecificRole",
+                "TargetAudienceAllCompanies",
+                "TargetAudienceSpecificCompany",
+                "TargetAudienceAllCustomers",
+                "TargetAudienceSpecificCustomer"
+            ]
+        },
         "response.APIError": {
             "type": "object",
             "properties": {
diff --git a/cmd/web/docs/swagger.yaml b/cmd/web/docs/swagger.yaml
index 1cd2cbb..f76b758 100644
--- a/cmd/web/docs/swagger.yaml
+++ b/cmd/web/docs/swagger.yaml
@@ -666,6 +666,8 @@ definitions:
         type: array
       schedule:
         $ref: '#/definitions/notification.ScheduleRequest'
+      target:
+        $ref: '#/definitions/notification.TargetAudienceType'
       tender:
         type: string
       title:
@@ -689,6 +691,8 @@ definitions:
         $ref: '#/definitions/notification.NotificationPriority'
       schedule:
         $ref: '#/definitions/notification.ScheduleResponse'
+      target:
+        $ref: '#/definitions/notification.TargetAudienceType'
       tender:
         type: string
       title:
@@ -743,6 +747,26 @@ definitions:
       time:
         type: integer
     type: object
+  notification.TargetAudienceType:
+    enum:
+    - all_users
+    - specific_users
+    - all_role
+    - specific_role
+    - all_companies
+    - specific_company
+    - all_customers
+    - specific_customer
+    type: string
+    x-enum-varnames:
+    - TargetAudienceAllUsers
+    - TargetAudienceSpecificUsers
+    - TargetAudienceAllRole
+    - TargetAudienceSpecificRole
+    - TargetAudienceAllCompanies
+    - TargetAudienceSpecificCompany
+    - TargetAudienceAllCustomers
+    - TargetAudienceSpecificCustomer
   response.APIError:
     properties:
       code:
diff --git a/internal/assets/handler.go b/internal/assets/handler.go
index abd84ec..13eca1d 100644
--- a/internal/assets/handler.go
+++ b/internal/assets/handler.go
@@ -47,7 +47,7 @@ func (h *Handler) GetFlagSVG(c echo.Context) error {
 // AdminGetFlag returns a flag by country code (Admin)
 // @Summary Get flag by country code (Admin)
 // @Description Retrieve a country flag by its 3-letter country code for admin panel
-// @Tags Admin Flags
+// @Tags Admin-Flags
 // @Accept json
 // @Produce json
 // @Param country_code path string true "3-letter country code (e.g., POL, GRC)"