From da23e0a62f9753345969bb53f9ef5afbe658598c Mon Sep 17 00:00:00 2001
From: mohsentaba <s.hosseintaba98@gmail.com>
Date: Tue, 16 Jun 2026 11:06:45 +0330
Subject: [PATCH]  seagger doc fixed for countries and cities

---
 apps/api/views/api_views.py | 63 +++++++++++++++++++++++++++++++++----
 config/urls.py              |  2 +-
 2 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/apps/api/views/api_views.py b/apps/api/views/api_views.py
index d0d6b08..d136b8c 100644
--- a/apps/api/views/api_views.py
+++ b/apps/api/views/api_views.py
@@ -81,8 +81,30 @@ class CountryView(APIView):
     permission_classes = [AllowAny]
 
     @swagger_auto_schema(
-        operation_description="List of optimized countries with codes and names",
-        responses={200: openapi.Response(description="Countries list")} 
+        operation_description="List of optimized countries with codes and names. Supports locale translation based on request header (Accept-Language).",
+        responses={
+            200: openapi.Response(
+                description="List of countries sorted alphabetically by name",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_ARRAY,
+                    items=openapi.Schema(
+                        type=openapi.TYPE_OBJECT,
+                        properties={
+                            'code': openapi.Schema(type=openapi.TYPE_STRING, description="ISO 3166-1 alpha-2 country code", example="IR"),
+                            'name': openapi.Schema(type=openapi.TYPE_STRING, description="Localized country name", example="Iran (Islamic Republic of)")
+                        }
+                    )
+                ),
+                examples={
+                    "application/json": [
+                        {"code": "CN", "name": "China"},
+                        {"code": "IR", "name": "Iran (Islamic Republic of)"},
+                        {"code": "RU", "name": "Russian Federation (the)"},
+                        {"code": "TR", "name": "Türkiye"}
+                    ]
+                }
+            )
+        }
     )
     def get(self, request):
         try:
@@ -108,19 +130,48 @@ class CityListView(APIView):
     permission_classes = [AllowAny]
 
     @swagger_auto_schema(
-        operation_description="List of cities based on country code",
+        operation_description="List of cities filtered by country code. Supports locale translation based on request header (Accept-Language).",
         manual_parameters=[
             openapi.Parameter(
                 name='country_code',
                 in_=openapi.IN_QUERY,
                 description='Two-letter country code (e.g. IR, CN, TR)',
                 type=openapi.TYPE_STRING,
-                required=True
+                required=True,
+                example="IR"
             )
         ],
         responses={
-            200: openapi.Response(description="List of city names"),
-            400: openapi.Response(description="Country code is required or invalid")
+            200: openapi.Response(
+                description="List of city names sorted alphabetically",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_ARRAY,
+                    items=openapi.Schema(type=openapi.TYPE_STRING, description="City name", example="Abadan")
+                ),
+                examples={
+                    "application/json": [
+                        "Abadan",
+                        "Abadeh",
+                        "Abhar",
+                        "Ahvaz",
+                        "Tehran"
+                    ]
+                }
+            ),
+            400: openapi.Response(
+                description="Bad Request - country_code missing or invalid",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_OBJECT,
+                    properties={
+                        'error': openapi.Schema(type=openapi.TYPE_STRING, description="Error message description", example="country_code query parameter is required")
+                    }
+                ),
+                examples={
+                    "application/json": {
+                        "error": "country_code query parameter is required"
+                    }
+                }
+            )
         }
     )
     def get(self, request):
diff --git a/config/urls.py b/config/urls.py
index ca0e222..0aa1c48 100644
--- a/config/urls.py
+++ b/config/urls.py
@@ -69,7 +69,7 @@ def oneapi_translate(request):
 
 
 api_patterns = [
-    path('', include('apps.api.urls')),
+    path('list/', include('apps.api.urls')),
 
     path('account/', include('apps.account.urls')),
     path('courses/', include('apps.course.urls')),