feat: swagger docs (#50)

* feat: init swag

* feat: relay swagger

* feat: swag workflow

* fix: fmt swagger commend

* docs: swagger readme

* feat: relay swag headers

Author: zijiren233

.github/workflows/release.yml

@@ -47,7 +47,7 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      
+
       - name: Download tiktoken
         run: |
           bash common/tiktoken/assest.sh
@@ -57,6 +57,11 @@ jobs:
         with:
           go-version: "1.23"
 
+      - name: Generate Swagger
+        run: |
+          go install github.com/swaggo/swag/cmd/swag@latest
+          swag init
+
       - name: Build
         run: |
           export GOOS=${{ matrix.targets.GOOS }}

Dockerfile

@@ -8,6 +8,10 @@ RUN apk add --no-cache curl
 
 RUN sh common/tiktoken/assest.sh
 
+RUN go install github.com/swaggo/swag/cmd/swag@latest
+
+RUN swag init
+
 RUN go build -trimpath -tags "jsoniter" -ldflags "-s -w" -o aiproxy
 
 FROM alpine:latest

README.md

@@ -33,6 +33,7 @@ Next-generation AI gateway, using OpenAI as the protocol entry point.
 - Think model support `<think>` split to `reasoning_content`
 - Prompt Token Cache billing support
 - Inline tiktoken, no need to download tiktoken file
+- API `Swagger` documentation support `http://host:port/swagger/index.html`
 
 ## Deploy
 

README.zh.md

@@ -34,6 +34,7 @@
 - Think 模型支持 `<think>` 切分到 `reasoning_content`
 - 提示词缓存计费支持
 - 内敛分词器，无需额外下载 tiktoken 文件
+- API `Swagger` 文档支持 `http://host:port/swagger/index.html`
 
 ## 部署
 

controller/channel-billing.go

@@ -9,14 +9,11 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
-	"github.com/labring/aiproxy/common/balance"
 	"github.com/labring/aiproxy/common/notify"
 	"github.com/labring/aiproxy/middleware"
 	"github.com/labring/aiproxy/model"
 	"github.com/labring/aiproxy/relay/adaptor"
-	"github.com/labring/aiproxy/relay/adaptor/openai"
 	"github.com/labring/aiproxy/relay/channeltype"
-	log "github.com/sirupsen/logrus"
 )
 
 // https://github.com/labring/aiproxy/issues/79
@@ -43,6 +40,16 @@ func updateChannelBalance(channel *model.Channel) (float64, error) {
 	return 0, nil
 }
 
+// UpdateChannelBalance godoc
+//
+//	@Summary		Update channel balance
+//	@Description	Updates the balance for a single channel
+//	@Tags			channel
+//	@Produce		json
+//	@Security		ApiKeyAuth
+//	@Param			id	path		int	true	"Channel ID"
+//	@Success		200	{object}	middleware.APIResponse{data=float64}
+//	@Router			/api/channel/{id}/balance [get]
 func UpdateChannelBalance(c *gin.Context) {
 	id, err := strconv.Atoi(c.Param("id"))
 	if err != nil {
@@ -69,11 +76,7 @@ func UpdateChannelBalance(c *gin.Context) {
 		})
 		return
 	}
-	c.JSON(http.StatusOK, middleware.APIResponse{
-		Success: true,
-		Message: "",
-		Data:    balance,
-	})
+	middleware.SuccessResponse(c, balance)
 }
 
 func updateAllChannelsBalance() error {
@@ -105,6 +108,15 @@ func updateAllChannelsBalance() error {
 	return nil
 }
 
+// UpdateAllChannelsBalance godoc
+//
+//	@Summary		Update all channels balance
+//	@Description	Updates the balance for all channels
+//	@Tags			channel
+//	@Produce		json
+//	@Security		ApiKeyAuth
+//	@Success		200	{object}	middleware.APIResponse
+//	@Router			/api/channels/balance [get]
 func UpdateAllChannelsBalance(c *gin.Context) {
 	err := updateAllChannelsBalance()
 	if err != nil {
@@ -120,33 +132,3 @@ func UpdateChannelsBalance(frequency time.Duration) {
 		_ = updateAllChannelsBalance()
 	}
 }
-
-// subscription
-func GetSubscription(c *gin.Context) {
-	group := middleware.GetGroup(c)
-	b, _, err := balance.GetGroupRemainBalance(c, *group)
-	if err != nil {
-		if errors.Is(err, balance.ErrNoRealNameUsedAmountLimit) {
-			middleware.ErrorResponse(c, http.StatusForbidden, err.Error())
-			return
-		}
-		log.Errorf("get group (%s) balance failed: %s", group.ID, err)
-		middleware.ErrorResponse(c, http.StatusInternalServerError, fmt.Sprintf("get group (%s) balance failed", group.ID))
-		return
-	}
-	token := middleware.GetToken(c)
-	quota := token.Quota
-	if quota <= 0 {
-		quota = b
-	}
-	c.JSON(http.StatusOK, openai.SubscriptionResponse{
-		HardLimitUSD:       quota + token.UsedAmount,
-		SoftLimitUSD:       b,
-		SystemHardLimitUSD: quota + token.UsedAmount,
-	})
-}
-
-func GetUsage(c *gin.Context) {
-	token := middleware.GetToken(c)
-	c.JSON(http.StatusOK, openai.UsageResponse{TotalUsage: token.UsedAmount * 100})
-}

controller/channel-test.go

@@ -25,7 +25,7 @@ import (
 	"github.com/labring/aiproxy/monitor"
 	"github.com/labring/aiproxy/relay/channeltype"
 	"github.com/labring/aiproxy/relay/meta"
-	"github.com/labring/aiproxy/relay/relaymode"
+	"github.com/labring/aiproxy/relay/mode"
 	"github.com/labring/aiproxy/relay/utils"
 	log "github.com/sirupsen/logrus"
 )
@@ -60,7 +60,7 @@ func testSingleModel(mc *model.ModelCaches, channel *model.Channel, modelName st
 	if !ok {
 		return nil, errors.New(modelName + " model config not found")
 	}
-	if modelConfig.Type == relaymode.Unknown {
+	if modelConfig.Type == mode.Unknown {
 		newModelConfig := guessModelConfig(modelName)
 		if newModelConfig != nil {
 			modelConfig = newModelConfig
@@ -81,7 +81,7 @@ func testSingleModel(mc *model.ModelCaches, channel *model.Channel, modelName st
 		}, nil
 	}
 
-	body, mode, err := utils.BuildRequest(modelConfig)
+	body, m, err := utils.BuildRequest(modelConfig)
 	if err != nil {
 		return nil, err
 	}
@@ -97,23 +97,23 @@ func testSingleModel(mc *model.ModelCaches, channel *model.Channel, modelName st
 
 	meta := meta.NewMeta(
 		channel,
-		mode,
+		m,
 		modelName,
 		modelConfig,
 		meta.WithRequestID(channelTestRequestID),
 	)
-	relayController, ok := relayController(mode)
+	relayController, ok := relayController(m)
 	if !ok {
-		return nil, fmt.Errorf("relay mode %d not implemented", mode)
+		return nil, fmt.Errorf("relay mode %d not implemented", m)
 	}
 	result := relayController(meta, newc)
 	success := result.Error == nil
 	var respStr string
 	var code int
 	if success {
 		switch meta.Mode {
-		case relaymode.AudioSpeech,
-			relaymode.ImagesGenerations:
+		case mode.AudioSpeech,
+			mode.ImagesGenerations:
 			respStr = ""
 		default:
 			respStr = w.Body.String()
@@ -136,6 +136,18 @@ func testSingleModel(mc *model.ModelCaches, channel *model.Channel, modelName st
 	)
 }
 
+// TestChannel godoc
+//
+//	@Summary		Test channel model
+//	@Description	Tests a single model in the channel
+//	@Tags			channel
+//	@Produce		json
+//	@Security		ApiKeyAuth
+//	@Param			id		path		int		true	"Channel ID"
+//	@Param			model	path		string	true	"Model name"
+//	@Success		200		{object}	middleware.APIResponse{data=model.ChannelTest}
+//	@Router			/api/channel/{id}/{model} [get]
+//
 //nolint:goconst
 func TestChannel(c *gin.Context) {
 	id, err := strconv.Atoi(c.Param("id"))
@@ -193,13 +205,13 @@ func TestChannel(c *gin.Context) {
 	})
 }
 
-type testResult struct {
+type TestResult struct {
 	Data    *model.ChannelTest `json:"data,omitempty"`
 	Message string             `json:"message,omitempty"`
 	Success bool               `json:"success"`
 }
 
-func processTestResult(mc *model.ModelCaches, channel *model.Channel, modelName string, returnSuccess bool, successResponseBody bool) *testResult {
+func processTestResult(mc *model.ModelCaches, channel *model.Channel, modelName string, returnSuccess bool, successResponseBody bool) *TestResult {
 	ct, err := testSingleModel(mc, channel, modelName)
 
 	e := &utils.UnsupportedModelTypeError{}
@@ -208,7 +220,7 @@ func processTestResult(mc *model.ModelCaches, channel *model.Channel, modelName
 		return nil
 	}
 
-	result := &testResult{
+	result := &TestResult{
 		Success: err == nil,
 	}
 	if err != nil {
@@ -232,6 +244,16 @@ func processTestResult(mc *model.ModelCaches, channel *model.Channel, modelName
 	return result
 }
 
+// TestChannelModels godoc
+//
+//	@Summary		Test channel models
+//	@Description	Tests all models in the channel
+//	@Tags			channel
+//	@Produce		json
+//	@Security		ApiKeyAuth
+//	@Param			id	path		int	true	"Channel ID"
+//	@Success		200	{object}	middleware.APIResponse{data=[]TestResult}
+//	@Router			/api/channel/{id}/models [get]
 func TestChannelModels(c *gin.Context) {
 	id, err := strconv.Atoi(c.Param("id"))
 	if err != nil {
@@ -259,7 +281,7 @@ func TestChannelModels(c *gin.Context) {
 		common.SetEventStreamHeaders(c)
 	}
 
-	results := make([]*testResult, 0)
+	results := make([]*TestResult, 0)
 	resultsMutex := sync.Mutex{}
 	hasError := atomic.Bool{}
 
@@ -318,6 +340,16 @@ func TestChannelModels(c *gin.Context) {
 	}
 }
 
+// TestAllChannels godoc
+//
+//	@Summary		Test all channels
+//	@Description	Tests all channels
+//	@Tags			channel
+//	@Produce		json
+//	@Security		ApiKeyAuth
+//	@Success		200	{object}	middleware.APIResponse{data=[]TestResult}
+//
+// @Router			/api/channels/test [get]
 func TestAllChannels(c *gin.Context) {
 	testDisabled := c.Query("test_disabled") == "true"
 	var channels []*model.Channel
@@ -342,7 +374,7 @@ func TestAllChannels(c *gin.Context) {
 		common.SetEventStreamHeaders(c)
 	}
 
-	results := make([]*testResult, 0)
+	results := make([]*TestResult, 0)
 	resultsMutex := sync.Mutex{}
 	hasErrorMap := make(map[int]*atomic.Bool)