1. 安装 swag

go get github.com/swaggo/swag/cmd/swag

2. 生成文件

首次生成相关文件，后期代码修改过，添加swag注解后，都需要在go 项目中（包含main.go）的目录，使用swag init命令生成相关文件，执行完上述命令后，如果写的注释格式没问题，项目根目录下会多出一个docs文件夹。

swag init

如果输入命令出现“不是内部或外部命令”、“swag init command not found”，cd到这个路径

cd C:\Users\username\go\pkg\mod\github.com\swaggo\swag@v1.8.7\cmd\swag

然后执行

go install

再cd到路径

cd C:\Users\username\go\bin

这个文件夹下面有swag.exe 将这个路径添加到环境变量，重开cmd窗口即可

3. 安装 gin-swagger

go get -u github.com/swaggo/gin-swagger

4. 集成

4.1 基础信息

在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容

package router

import (
	_ "nmc_website/docs"
	"nmc_website/service"

	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func Router() *gin.Engine {
	gin.SetMode(gin.ReleaseMode)
	r := gin.Default()
	r.LoadHTMLGlob("template/*")
	// 注册Swagger api相关路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	r.GET("/ping", service.Ping)
	return r
}

// @title 标题
// @version 1.0 版本
// @description 描述
// @termsOfService http://swagger.io/terms/
// @contact.name 联系人
// @contact.url http://www.swagger.io/support
// @contact.email 584807419@qq.com
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host videotools.cn
// @BasePath /freeapi/v1
// @query.collection.format multi
func main() {
	r := Router()
	r.Run("0.0.0.0:80")
}

项目程序运行起来，打开浏览器访问http://localhost:80/swagger/index.html

gin-swagger 提供了 DisablingWrapHandler 函数，方便通过设置环境变量禁用Swagger。

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

如果将环境变量 NAME_OF_ENV_VARIABLE设置为任意值，则 /swagger/*any 返回404响应，就像未指定路由一样。

4.2 简单示例

4.2.1 GET

// GetList
// @Summary 摘要
// @Schemes
// @Description 描述
// @Tags 标签
// @Param Id query int true "参数描述" 分别表示 ：@Param 参数名 位置（query或path或body） 类型 是否必需 注释
// @Param object query models.ParamList false "查询参数"
// @Accept json
// @Produce json
// @Success 200 {object} Model._ResponseList 返回结果 200 类型（object就是结构体） 类型 注释
// @Router /user [get]
 func GetList(g *gin.Context)  {
  g.JSON(http.StatusOK, nil) 
}

//注释中参数类型使用了 `object`，`models.ParamList` 具体定义如下：
// ParamList 获取列表query string参数
type ParamList struct {
	ID int64  `json:"id" form:"id"`   // 可以为空
	Page        int64  `json:"page" form:"page" example:"1"`       // 页码
	Size        int64  `json:"size" form:"size" example:"10"`      // 每页数据量
	Order       string `json:"order" form:"order" example:"score"` // 排序依据
}

// _ResponseList 列表接口响应数据
type _ResponseList struct {
	Code    ResCode                 `json:"code"`    // 响应状态码
	Message string                  `json:"message"` // 提示信息
	Data    []*models.ApiPostDetail `json:"data"`    // 数据
}

其他
// @Security ApiKeyAuth
// @Param Authorization header string false "Bearer 用户令牌"
// @Accept application/json
// @Produce application/json
// @Success 200 {string} json "{"code":"200", "data":"response data"}"

4.2.2 PUT

// @Summary 修改
// @Schemes
// @Description update
// @Tags ops
// @Param userinput body Model.UserUpdateInput true "入参"
// @Accept json
// @Produce json
// @Success 200 {object} Model.ResponseResult UpdateUser
// @Router /user [put]
func UpdateData(g *gin.Context) {
}

再过5分钟你就能了解如何使用 Gin + Swagger 啦