docs: add API docs

Author: songquanpeng

controller/user.go

@@ -180,27 +180,27 @@ func Register(c *gin.Context) {
 }
 
 func GetAllUsers(c *gin.Context) {
-    p, _ := strconv.Atoi(c.Query("p"))
-    if p < 0 {
-        p = 0
-    }
-    
-    order := c.DefaultQuery("order", "")
-    users, err := model.GetAllUsers(p*config.ItemsPerPage, config.ItemsPerPage, order)
-	
-    if err != nil {
-        c.JSON(http.StatusOK, gin.H{
-            "success": false,
-            "message": err.Error(),
-        })
-        return
-    }
-    
-    c.JSON(http.StatusOK, gin.H{
-        "success": true,
-        "message": "",
-        "data":    users,
-    })
+	p, _ := strconv.Atoi(c.Query("p"))
+	if p < 0 {
+		p = 0
+	}
+
+	order := c.DefaultQuery("order", "")
+	users, err := model.GetAllUsers(p*config.ItemsPerPage, config.ItemsPerPage, order)
+
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"success": false,
+			"message": err.Error(),
+		})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"success": true,
+		"message": "",
+		"data":    users,
+	})
 }
 
 func SearchUsers(c *gin.Context) {
@@ -770,3 +770,38 @@ func TopUp(c *gin.Context) {
 	})
 	return
 }
+
+type adminTopUpRequest struct {
+	UserId int    `json:"user_id"`
+	Quota  int    `json:"quota"`
+	Remark string `json:"remark"`
+}
+
+func AdminTopUp(c *gin.Context) {
+	req := adminTopUpRequest{}
+	err := c.ShouldBindJSON(&req)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"success": false,
+			"message": err.Error(),
+		})
+		return
+	}
+	err = model.IncreaseUserQuota(req.UserId, int64(req.Quota))
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{
+			"success": false,
+			"message": err.Error(),
+		})
+		return
+	}
+	if req.Remark == "" {
+		req.Remark = fmt.Sprintf("通过 API 充值 %s", common.LogQuota(int64(req.Quota)))
+	}
+	model.RecordTopupLog(req.UserId, req.Remark, req.Quota)
+	c.JSON(http.StatusOK, gin.H{
+		"success": true,
+		"message": "",
+	})
+	return
+}

docs/API.md

@@ -1,6 +1,10 @@
 # 使用 API 操控 & 扩展 One API
 > 欢迎提交 PR 在此放上你的拓展项目。
 
+例如，虽然 One API 本身没有直接支持支付，但是你可以通过系统扩展的 API 来实现支付功能。
+
+又或者你想自定义渠道管理策略，也可以通过 API 来实现渠道的禁用与启用。
+
 ## 鉴权
 One API 支持两种鉴权方式：Cookie 和 Token，对于 Token，参照下图获取：
 
@@ -9,9 +13,32 @@ One API 支持两种鉴权方式：Cookie 和 Token，对于 Token，参照下
 之后，将 Token 作为请求头的 Authorization 字段的值即可，例如下面使用 Token 调用测试渠道的 API：
 ![image](https://github.com/songquanpeng/songquanpeng.github.io/assets/39998050/1273b7ae-cb60-4c0d-93a6-b1cbc039c4f8)
 
+## 请求格式与响应格式
+One API 使用 JSON 格式进行请求和响应。
+
+对于响应体，一般格式如下：
+```json
+{
+  "message": "请求信息",
+  "success": true,
+  "data": {}
+}
+```
+
 ## API 列表
 > 当前 API 列表不全，请自行通过浏览器抓取前端请求
 
-欢迎此处 PR 补充。
+如果现有的 API 没有办法满足你的需求，欢迎提交 issue 讨论。
+
+### 获取当前登录用户信息
+**GET** `/api/user/self`
 
-如果现有的 API 没有办法满足你的需求，欢迎提交 issue 讨论。
+### 为给定用户充值额度
+**POST** `/api/topup`
+```json
+{
+  "user_id": 1,
+  "quota": 100000,
+  "remark": "充值 100000 额度"
+}
+```

model/log.go

@@ -51,6 +51,21 @@ func RecordLog(userId int, logType int, content string) {
 	}
 }
 
+func RecordTopupLog(userId int, content string, quota int) {
+	log := &Log{
+		UserId:    userId,
+		Username:  GetUsernameById(userId),
+		CreatedAt: helper.GetTimestamp(),
+		Type:      LogTypeTopup,
+		Content:   content,
+		Quota:     quota,
+	}
+	err := LOG_DB.Create(log).Error
+	if err != nil {
+		logger.SysError("failed to record log: " + err.Error())
+	}
+}
+
 func RecordConsumeLog(ctx context.Context, userId int, channelId int, promptTokens int, completionTokens int, modelName string, tokenName string, quota int64, content string) {
 	logger.Info(ctx, fmt.Sprintf("record consume log: userId=%d, channelId=%d, promptTokens=%d, completionTokens=%d, modelName=%s, tokenName=%s, quota=%d, content=%s", userId, channelId, promptTokens, completionTokens, modelName, tokenName, quota, content))
 	if !config.LogConsumeEnabled {

router/api-router.go

@@ -26,6 +26,7 @@ func SetApiRouter(router *gin.Engine) {
 		apiRouter.GET("/oauth/wechat", middleware.CriticalRateLimit(), controller.WeChatAuth)
 		apiRouter.GET("/oauth/wechat/bind", middleware.CriticalRateLimit(), middleware.UserAuth(), controller.WeChatBind)
 		apiRouter.GET("/oauth/email/bind", middleware.CriticalRateLimit(), middleware.UserAuth(), controller.EmailBind)
+		apiRouter.POST("/topup", middleware.AdminAuth(), controller.AdminTopUp)
 
 		userRoute := apiRouter.Group("/user")
 		{