docs(api): 补全 OpenAPI 上传与系统设置文档

为文件上传、静态资源和文件存储设置接口补齐注释，并同步更新生成的 Swagger 文档。

apps/api/internal/httpapi/file_upload_handlers.go

@@ -11,6 +11,22 @@ import (
 
 const maxGatewayUploadBytes = 256 << 20
 
+// uploadFile godoc
+// @Summary 上传文件
+// @Description 上传文件到配置的文件存储通道；没有启用通道时回退到本地静态上传目录。单文件最大 256MiB。
+// @Tags files
+// @Accept multipart/form-data
+// @Produce json
+// @Security BearerAuth
+// @Param file formData file true "要上传的文件"
+// @Param source formData string false "上传来源标识" default(ai-gateway-openapi)
+// @Success 200 {object} FileUploadResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 502 {object} ErrorEnvelope
+// @Failure 503 {object} ErrorEnvelope
+// @Router /api/v1/files/upload [post]
+// @Router /v1/files/upload [post]
 func (s *Server) uploadFile(w http.ResponseWriter, r *http.Request) {
 	r.Body = http.MaxBytesReader(w, r.Body, maxGatewayUploadBytes)
 	if err := r.ParseMultipartForm(32 << 20); err != nil {