Gin + Swagger快速生成API文档

在开发过程中，我们不免需要调试我们的接口，但是有些接口测试工具无法根据我们的接口变化而动态变化。文档和代码是分离的。总是出现文档和代码不同步的情况。这个时候就可以在我们项目中引入swagger，方便后期维护以及他人快速上手项目

安装 swag

$ go get -u github.com/swaggo/swag/cmd/swag 
# 1.16 及以上版本 
$ go install github.com/swaggo/swag/cmd/swag@latest

生成文件

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

swag init

安装 gin-swagger

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

error

swag init 如果输入命令出现“不是内部或外部命令”、“swag init command not found”，cd到这个路径 cd C:\Users\username\go\pkg\mod\github.com\swaggo\swag@v1.8.7\cmd\swag

# cd C:\Users\Lenovo\go\pkg\mod\github.com\swaggo\swag@v1.16.6\cmd\swag
go install

# 再cd到路径 cd C:\Users\username\go\bin
# 这个文件夹下面有swag.exe 将这个路径添加到环境变量，重开cmd窗口即可

集成

基础信息

package router

import (
	_ "leo-gin/docs"

	"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))
	return r
}

// @title 项目接口
// @version 1.0 版本
// @description 这是项目API接口文档
// @host http://localhost:8080
// @BasePath /api
func main() {
	r := Router()
	r.Run("0.0.0.0:80")
}

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

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"`    // 数据
}

Get请求

// @Summary 查看迁移任务详细信息
// @Description 查看迁移任务详细信息
// @Accept json
// @Produce  json
// @Param task_id path string true "task_id"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [get]

Post请求

// @Summary 创建镜像迁移任务
// @Description 创建镜像迁移任务
// @Accept  json
// @Produce  json
// @Param data body models.CreateTaskReq true "请示参数data"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [post]

Delete请求

// @Summary 删除镜像迁移任务
// @Description 删除镜像迁移任务
// @Accept  json
// @Produce  json
// @Param data body models.TaskReq true "请示参数data"
// @Success 200 {object} models.Response "请求成功"
// @Failure 400 {object} models.ResponseErr "请求错误"
// @Failure 500 {object} models.ResponseErr "内部错误"
// @Router /task [delete]

其他

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