fix: correct documentation for non 200 responses in swagger

services/context/api.go

@@ -58,40 +58,69 @@ func init() {
 //            if we need to indicate some errors, we should introduce some new fields like ErrorCode or ErrorType
 // * url:     the swagger document URL
 
+type APIError struct {
+	Message string `json:"message"`
+	URL     string `json:"url"`
+}
+
 // APIError is error format response
 // swagger:response error
-type APIError struct {
+type swaggerAPIError struct {
+	// in:body
+	Body APIError `json:"body"`
+}
+
+type APIValidationError struct {
 	Message string `json:"message"`
 	URL     string `json:"url"`
 }
 
 // APIValidationError is error format response related to input validation
 // swagger:response validationError
-type APIValidationError struct {
+type swaggerAPIValidationError struct {
-	Message string `json:"message"`
+	// in:body
-	URL     string `json:"url"`
+	Body APIValidationError `json:"body"`
+}
+
+type APIInvalidTopicsError struct {
+	Message       string   `json:"message"`
+	InvalidTopics []string `json:"invalidTopics"`
 }
 
 // APIInvalidTopicsError is error format response to invalid topics
 // swagger:response invalidTopicsError
-type APIInvalidTopicsError struct {
+type swaggerAPIInvalidTopicsError struct {
-	Message       string   `json:"message"`
+	// in:body
-	InvalidTopics []string `json:"invalidTopics"`
+	Body APIInvalidTopicsError `json:"body"`
 }
 
 // APIEmpty is an empty response
 // swagger:response empty
 type APIEmpty struct{}
 
-// APIForbiddenError is a forbidden error response
-// swagger:response forbidden
 type APIForbiddenError struct {
 	APIError
 }
 
-// APINotFound is a not found empty response
+// APIForbiddenError is a forbidden error response
+// swagger:response forbidden
+type swaggerAPIForbiddenError struct {
+	// in:body
+	Body APIForbiddenError `json:"body"`
+}
+
+type APINotFound struct {
+	Message string   `json:"message"`
+	URL     string   `json:"url"`
+	Errors  []string `json:"errors"`
+}
+
+// APINotFound is a not found error response
 // swagger:response notFound
-type APINotFound struct{}
+type swaggerAPINotFound struct {
+	// in:body
+	Body APINotFound `json:"body"`
+}
 
 // APIConflict is a conflict empty response
 // swagger:response conflict
@@ -105,12 +134,17 @@ type APIRedirect struct{}
 // swagger:response string
 type APIString string
 
-// APIRepoArchivedError is an error that is raised when an archived repo should be modified
-// swagger:response repoArchivedError
 type APIRepoArchivedError struct {
 	APIError
 }
 
+// APIRepoArchivedError is an error that is raised when an archived repo should be modified
+// swagger:response repoArchivedError
+type swaggerAPIRepoArchivedError struct {
+	// in:body
+	Body APIRepoArchivedError `json:"body"`
+}
+
 // ServerError responds with error message, status is 500
 func (ctx *APIContext) ServerError(title string, err error) {
 	ctx.Error(http.StatusInternalServerError, title, err)
@@ -251,7 +285,7 @@ func APIContexter() func(http.Handler) http.Handler {
 // String will replace message, errors will be added to a slice
 func (ctx *APIContext) NotFound(objs ...any) {
 	message := ctx.Locale.TrString("error.not_found")
-	var errors []string
+	errors := make([]string, 0)
 	for _, obj := range objs {
 		// Ignore nil
 		if obj == nil {
@@ -265,10 +299,10 @@ func (ctx *APIContext) NotFound(objs ...any) {
 		}
 	}
 
-	ctx.JSON(http.StatusNotFound, map[string]any{
+	ctx.JSON(http.StatusNotFound, APINotFound{
-		"message": message,
+		Message: message,
-		"url":     setting.API.SwaggerURL,
+		URL:     setting.API.SwaggerURL,
-		"errors":  errors,
+		Errors:  errors,
 	})
 }
 

templates/swagger/v1_json.tmpl

@@ -19708,6 +19708,86 @@
       },
       "x-go-package": "code.gitea.io/gitea/modules/structs"
     },
+    "APIForbiddenError": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "x-go-name": "Message"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/services/context"
+    },
+    "APIInvalidTopicsError": {
+      "type": "object",
+      "properties": {
+        "invalidTopics": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-go-name": "InvalidTopics"
+        },
+        "message": {
+          "type": "string",
+          "x-go-name": "Message"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/services/context"
+    },
+    "APINotFound": {
+      "type": "object",
+      "properties": {
+        "errors": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-go-name": "Errors"
+        },
+        "message": {
+          "type": "string",
+          "x-go-name": "Message"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/services/context"
+    },
+    "APIRepoArchivedError": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "x-go-name": "Message"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/services/context"
+    },
+    "APIValidationError": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "x-go-name": "Message"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/services/context"
+    },
     "AccessToken": {
       "type": "object",
       "title": "AccessToken represents an API access token.",
@@ -28202,42 +28282,27 @@
     },
     "error": {
       "description": "APIError is error format response",
-      "headers": {
+      "schema": {
-        "message": {
+        "$ref": "#/definitions/APIError"
-          "type": "string"
-        },
-        "url": {
-          "type": "string"
-        }
       }
     },
     "forbidden": {
       "description": "APIForbiddenError is a forbidden error response",
-      "headers": {
+      "schema": {
-        "message": {
+        "$ref": "#/definitions/APIForbiddenError"
-          "type": "string"
-        },
-        "url": {
-          "type": "string"
-        }
       }
     },
     "invalidTopicsError": {
       "description": "APIInvalidTopicsError is error format response to invalid topics",
-      "headers": {
+      "schema": {
-        "invalidTopics": {
+        "$ref": "#/definitions/APIInvalidTopicsError"
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "message": {
-          "type": "string"
-        }
       }
     },
     "notFound": {
-      "description": "APINotFound is a not found empty response"
+      "description": "APINotFound is a not found error response",
+      "schema": {
+        "$ref": "#/definitions/APINotFound"
+      }
     },
     "parameterBodies": {
       "description": "parameterBodies",
@@ -28265,13 +28330,8 @@
     },
     "repoArchivedError": {
       "description": "APIRepoArchivedError is an error that is raised when an archived repo should be modified",
-      "headers": {
+      "schema": {
-        "message": {
+        "$ref": "#/definitions/APIRepoArchivedError"
-          "type": "string"
-        },
-        "url": {
-          "type": "string"
-        }
       }
     },
     "string": {
@@ -28282,13 +28342,8 @@
     },
     "validationError": {
       "description": "APIValidationError is error format response related to input validation",
-      "headers": {
+      "schema": {
-        "message": {
+        "$ref": "#/definitions/APIValidationError"
-          "type": "string"
-        },
-        "url": {
-          "type": "string"
-        }
       }
     }
   },