From 560535a97f4a0e638215031750e0a276349b1aaf Mon Sep 17 00:00:00 2001
From: Giteabot <teabot@gitea.io>
Date: Thu, 23 Jul 2026 00:27:47 -0700
Subject: [PATCH] fix(api): align Swagger schemas for UserSettings and
 TopicListResponse (#38590) (#38592)

Backport #38590

Signed-off-by: Sudhanshu Singh <sudhanshuwriterblc@gmail.com>
Co-authored-by: Shudhanshu Singh <sudhanshuwriterblc@gmail.com>
---
 modules/structs/repo_topic.go           |  5 +++++
 routers/api/v1/repo/topic.go            |  4 ++--
 routers/api/v1/swagger/repo.go          |  2 +-
 routers/api/v1/swagger/user.go          |  2 +-
 templates/swagger/v1_json.tmpl          | 24 ++++++++++++++++--------
 templates/swagger/v1_openapi3_json.tmpl | 24 ++++++++++++++++--------
 6 files changed, 41 insertions(+), 20 deletions(-)

diff --git a/modules/structs/repo_topic.go b/modules/structs/repo_topic.go
index 6a79297943..4ddf5edc76 100644
--- a/modules/structs/repo_topic.go
+++ b/modules/structs/repo_topic.go
@@ -32,3 +32,8 @@ type RepoTopicOptions struct {
 	// list of topic names
 	Topics []string `json:"topics"`
 }
+
+// TopicListResponse returns a list of TopicResponse
+type TopicListResponse struct {
+	Topics []*TopicResponse `json:"topics"`
+}
diff --git a/routers/api/v1/repo/topic.go b/routers/api/v1/repo/topic.go
index 9009e1d8db..00fef50595 100644
--- a/routers/api/v1/repo/topic.go
+++ b/routers/api/v1/repo/topic.go
@@ -300,7 +300,7 @@ func TopicSearch(ctx *context.APIContext) {
 	}
 
 	ctx.SetTotalCountHeader(total)
-	ctx.JSON(http.StatusOK, map[string]any{
-		"topics": topicResponses,
+	ctx.JSON(http.StatusOK, api.TopicListResponse{
+		Topics: topicResponses,
 	})
 }
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
index e9a3a15821..0d52d97f8b 100644
--- a/routers/api/v1/swagger/repo.go
+++ b/routers/api/v1/swagger/repo.go
@@ -348,7 +348,7 @@ type swaggerFileDeleteResponse struct {
 // swagger:response TopicListResponse
 type swaggerTopicListResponse struct {
 	// in: body
-	Body []api.TopicResponse `json:"body"`
+	Body api.TopicListResponse `json:"body"`
 }
 
 // TopicNames
diff --git a/routers/api/v1/swagger/user.go b/routers/api/v1/swagger/user.go
index 16be01fd34..c10b373601 100644
--- a/routers/api/v1/swagger/user.go
+++ b/routers/api/v1/swagger/user.go
@@ -46,7 +46,7 @@ type swaggerResponseUserHeatmapData struct {
 // swagger:response UserSettings
 type swaggerResponseUserSettings struct {
 	// in:body
-	Body []api.UserSettings `json:"body"`
+	Body api.UserSettings `json:"body"`
 }
 
 // BadgeList
diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl
index 41e4209648..7735ecb4b4 100644
--- a/templates/swagger/v1_json.tmpl
+++ b/templates/swagger/v1_json.tmpl
@@ -30294,6 +30294,20 @@
       },
       "x-go-package": "gitea.dev/modules/structs"
     },
+    "TopicListResponse": {
+      "description": "TopicListResponse returns a list of TopicResponse",
+      "type": "object",
+      "properties": {
+        "topics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/TopicResponse"
+          },
+          "x-go-name": "Topics"
+        }
+      },
+      "x-go-package": "gitea.dev/modules/structs"
+    },
     "TopicName": {
       "description": "TopicName a list of repo topic names",
       "type": "object",
@@ -31920,10 +31934,7 @@
     "TopicListResponse": {
       "description": "TopicListResponse",
       "schema": {
-        "type": "array",
-        "items": {
-          "$ref": "#/definitions/TopicResponse"
-        }
+        "$ref": "#/definitions/TopicListResponse"
       }
     },
     "TopicNames": {
@@ -31974,10 +31985,7 @@
     "UserSettings": {
       "description": "UserSettings",
       "schema": {
-        "type": "array",
-        "items": {
-          "$ref": "#/definitions/UserSettings"
-        }
+        "$ref": "#/definitions/UserSettings"
       }
     },
     "VariableList": {
diff --git a/templates/swagger/v1_openapi3_json.tmpl b/templates/swagger/v1_openapi3_json.tmpl
index 6c97a74f45..2f817c207a 100644
--- a/templates/swagger/v1_openapi3_json.tmpl
+++ b/templates/swagger/v1_openapi3_json.tmpl
@@ -1452,10 +1452,7 @@
         "content": {
           "application/json": {
             "schema": {
-              "items": {
-                "$ref": "#/components/schemas/TopicResponse"
-              },
-              "type": "array"
+              "$ref": "#/components/schemas/TopicListResponse"
             }
           }
         },
@@ -1534,10 +1531,7 @@
         "content": {
           "application/json": {
             "schema": {
-              "items": {
-                "$ref": "#/components/schemas/UserSettings"
-              },
-              "type": "array"
+              "$ref": "#/components/schemas/UserSettings"
             }
           }
         },
@@ -10110,6 +10104,20 @@
         "type": "object",
         "x-go-package": "gitea.dev/modules/structs"
       },
+      "TopicListResponse": {
+        "description": "TopicListResponse returns a list of TopicResponse",
+        "properties": {
+          "topics": {
+            "items": {
+              "$ref": "#/components/schemas/TopicResponse"
+            },
+            "type": "array",
+            "x-go-name": "Topics"
+          }
+        },
+        "type": "object",
+        "x-go-package": "gitea.dev/modules/structs"
+      },
       "TopicName": {
         "description": "TopicName a list of repo topic names",
         "properties": {