Golang-Swagger - 技术栈

使用 Swagger 的优点：

主要优势

1. 自动生成交互式 API 文档

代码即文档：注释与代码同步，减少文档滞后

可视化界面：浏览器查看，无需单独维护文档

实时更新：修改代码注释后重新生成即可

2. 在线测试接口

无需 Postman/curl：直接在浏览器测试

参数自动填充：根据定义自动生成请求示例

实时查看响应：立即看到返回结果和状态码

3. 前后端协作效率提升

统一规范：前后端基于同一份 API 定义

减少沟通成本：接口参数、返回值一目了然

前端可提前开发：根据文档先做 Mock

4. 代码生成能力

客户端 SDK：可生成多语言客户端代码

服务端代码：部分框架支持生成服务端骨架

Mock 服务器：可生成 Mock 数据用于测试

5. API 版本管理

版本对比：查看不同版本差异

变更追踪：记录接口变更历史

向后兼容：帮助识别破坏性变更

6. 团队协作

新人上手快：快速了解接口

统一标准：团队使用同一套规范

减少错误：参数类型和格式清晰

7. 质量保证

参数验证：自动验证请求参数格式

类型检查：确保数据类型正确

错误提示：清晰的错误信息

实际使用

Swagger 集成方案

1. 安装依赖和工具

首先需要安装 swag 工具和依赖包：

复制代码

# 安装 swag 工具
go install github.com/swaggo/swag/cmd/swag@latest

# 添加依赖到 go.mod
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2. 创建 Swagger 主文档文件

创建 docs/docs.go 文件（Swagger 会自动生成，但需要先创建目录）：

复制代码

package docs

import "github.com/swaggo/gin-swagger/swaggerFiles"

// 这个文件会在运行 swag init 后自动生成
// 暂时先创建目录结构

3. 创建 Swagger 配置文件

创建 docs/swagger.yaml 或 docs/swagger.json（可选，swag 会自动生成）

4. 更新 API 文件添加 Swagger 注释

更新 api/v1/scheduled_borrow.go：

Go 复制代码

package v1

import (
	"LC-Trading-Hub/pkg/util"
	"LC-Trading-Hub/service"
	"net/http"

	"github.com/gin-gonic/gin"
)

// CreateScheduledBorrow 创建明日借券预订单
// @Summary 创建明日借券预订单
// @Description 创建一条明日开盘前要接的券的预订单记录
// @Tags 借券管理
// @Accept json
// @Produce json
// @Param request body service.CreateScheduledBorrowService true "预订单信息"
// @Success 200 {object} serializer.Response{data=serializer.ScheduledBorrow} "创建成功"
// @Failure 400 {object} serializer.Response "参数错误"
// @Failure 500 {object} serializer.Response "服务器错误"
// @Router /api/v1/borrow/scheduled [post]
func CreateScheduledBorrow(c *gin.Context) {
	var service service.CreateScheduledBorrowService
	if err := c.ShouldBindJSON(&service); err != nil {
		c.JSON(http.StatusBadRequest, ErrorResponse(err))
		util.LogrusObj.Errorf("Failed to bind create scheduled borrow service: %v", err)
		return
	}
	res := service.Create()
	util.LogrusObj.Infof("Create scheduled borrow service: %v", res)
	c.JSON(http.StatusOK, res)
}

// GetScheduledBorrowList 获取明日借券预订单列表
// @Summary 获取明日借券预订单列表
// @Description 获取明日借券预订单列表，支持分页和多种筛选条件
// @Tags 借券管理
// @Accept json
// @Produce json
// @Param page query int false "页码" default(1)
// @Param size query int false "每页数量" default(10)
// @Param scheduled_date query string false "计划执行日期(格式:YYYY-MM-DD)"
// @Param status query string false "状态筛选(pending=待执行,executed=已执行,cancelled=已取消)"
// @Param ticker query string false "股票代码筛选"
// @Param broker query string false "券商筛选"
// @Success 200 {object} serializer.Response{data=object{items=[]serializer.ScheduledBorrow,total=int}} "查询成功"
// @Failure 400 {object} serializer.Response "参数错误"
// @Failure 500 {object} serializer.Response "服务器错误"
// @Router /api/v1/borrow/scheduled [get]
func GetScheduledBorrowList(c *gin.Context) {
	var service service.GetScheduledBorrowListService
	if err := c.ShouldBind(&service); err != nil {
		c.JSON(http.StatusBadRequest, ErrorResponse(err))
		util.LogrusObj.Errorf("Failed to bind get scheduled borrow list service: %v", err)
		return
	}
	res := service.GetList()
	util.LogrusObj.Info("Get scheduled borrow list service")
	c.JSON(http.StatusOK, res)
}

5. 创建主文档注释文件

创建或更新 cmd/main.go 或项目根目录的 main.go，添加 Swagger 主文档注释：

Go 复制代码

// @title LC Trading Hub API
// @version 1.0
// @description LC Trading Hub 交易系统API文档
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8081
// @BasePath /api/v1

// @schemes http https
package main

如果没有 main.go，可以在 cmd/main.go 或创建一个 docs/swagger.go 文件。

6. 更新路由文件

更新 routes/router.go，添加 Swagger 路由

Go 复制代码

package routes

import (
	v1 "LC-Trading-Hub/api/v1"
	"LC-Trading-Hub/middleware"
	"LC-Trading-Hub/pkg/util"
	"net/http"

	"github.com/gin-contrib/gzip"
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func NewRouter() *gin.Engine {
	// ... 现有代码 ...

	r.StaticFS("/static", http.Dir("./static"))

	// Swagger 文档路由（内网访问）
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	api := r.Group("/api/v1")
	{
		// ... 现有路由 ...
	}
	
	return r
}

8. 访问 Swagger UI

启动服务后，访问：

http://localhost:8081/swagger/index.html（根据你的服务端口调整）