简述 Gin 框架如何集成swagger

简述Gin框架集成swagger过程

1、安装 swag

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

swag 用于生成 docs 文件夹(swagger文档程序使用)

安装完成后会在 ${GOPATH}/bin生成一个执行文件

2、安装依赖包

github.com/gin-gonic/gin
github.com/swaggo/gin-swagger

3、示例程序一

package main

import (
	_ "./docs"
	"github.com/gin-gonic/gin"
	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"net/http"
)


// @title 开发文档
// @version 0.0.1
// @BasePath /api/v1/

// @title  haimait.com开发文档
// @version 1.0
// @description  Golang api of demo
// @termsOfService haimait.com

// @contact.name API Support
// @contact.url haimait.com
// @contact.email ×××@qq.com
// @BasePath /api/v1/
func main() {
	r := gin.New()
        swagHandler := true
        if swagHandler {
		// 文档界面访问URL
		// http://127.0.0.1:8080/swagger/index.html
		r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	}

	// 创建路由组
	v1 := r.Group("/api/v1")

	v1.GET("/getUser/:id", getUser)

	r.Run()
}

// @Tags 测试
// @Summary  获取指定getUser记录1
// @Description 获取指定getUser记录2
// @Param Authorization	header string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
// @Accept  json
// @Product json
// @Param   id     query    int     true        "用户id"
// @Param   name   query    string  false        "用户name"
// @Success 200 {object} string	"{"code": 200, "data": [...]}"
// @Router /getUser/:id [get]
func getUser(c *gin.Context) {
	var r req
	Id:= c.DefaultQuery("id", "0")
	r.Id,_ = strconv.Atoi(Id)
	r.Name = c.DefaultQuery("name", "")
	Age, _ := strconv.Atoi(c.DefaultQuery("age", "0"))
	r.Age = Age
	fmt.Println(r)
	c.JSON(http.StatusOK, r)
}

type req struct {
	Id   int    `json:"id" form:"id" example:"1"`
	Name string `json:"name" form:"name" example:"用户name"`
	Age  int    `json:"age" form:"age" example:"123"`
}

4、生成文档

在项目执行 swag init

执行 go run main.go

进入 http://127.0.0.1:8080/swagger/index.html 查看文档

这些注释字段，我们一个个解释。

使用token

如果你的程序中使用了token中间键，只需要添加下面两行注释即可

// @Security x-token
// @param x-token header string true "Authorization"

4、示例程序二

type req struct {
	Id   int    `json:"id" form:"id" example:"1"`  //用户id
	Name string `json:"name" form:"name" example:"用户name"`  //用户姓名
	Age  int    `json:"age" form:"age" example:"123"`        //用户年龄
}

// @Summary  获取指定record记录1
// @Description 获取指定record记录2
// @Tags 测试
// @Accept  json
// @Product json
// @Param data body req true "请示参数data"
// @Success 200 {object} req
// @Router /updateUser [POST]
func updateUser(c *gin.Context) {
	var r req
	err := c.ShouldBindJSON(&r)
	fmt.Println("err11", err)
	c.JSON(http.StatusOK, r)
}

5、示例程序三

type GetOperationLogListResponse struct {
	List  *[]req `json:"list"`
	Total int    `json:"total"`
}
type req struct {
	Id   int    `json:"id" form:"id" example:"1"`  //用户id
	Name string `json:"name" form:"name" example:"用户name"`  //用户姓名
	Age  int    `json:"age" form:"age" example:"123"`        //用户年龄
}
// @Title 应用中心操作日志
// @Author mengyilingjian@outlook.com
// @Description 获取应用中心操作日志
// @Tags operationlog
// @Param Authorization	header string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
// @Param route formData string false "路由"
// @Param operator formData string false "操作者"
// @Param operation_type formData string false "操作类型 1 新增、2 删除、3 更新"
// @Param description formData string false "操作描述"
// @Param start_time formData int64 false "开始时间"
// @Param end_time formData int64 false "结束时间"
// @Param page formData int true "页数"
// @Param size formData int true "数据条数"
// @Success 200 {object} GetOperationLogListResponse "{"deploy_env": "测试deploy_env"}"
// @Router	/api/v1/appcenter [get]
func GetOperationLogList(c *gin.Context) {
	c.JSON(http.StatusOK, "ok")
}

6、示例程序四

type TemplateAddBody struct {
	Name               string `json:"name" example:"用户name"`
	DeployEnv          string `json:"deploy_env" example:"例子deploy_env"`
	GitlabType         int    `json:"gitlab_type" example:"1"`
	GitlabBranchName   string `json:"gitlab_branch_name" example:"例子description"`
	IsAutoRelease      int    `json:"is_auto_release" example:"12"`
	Description        string `json:"description" example:"例子description"`
	GitlabCITemplateID int32  `json:"gitlab_ci_template_id" example:"123"`
	GitlabID           uint32 `json:"gitlab_id" example:"222"`
}

// @Title 新增模版
// @Author mengyilingjian@outlook.com
// @Description 新增模版
// @Tags release template
// @Param Authorization	header	string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
// @Param body body	TemplateAddBody true "JSON数据"
// @Success 200 {object} TemplateAddBody
// @Router	/api/v1/release/template/add [post]
func ReleaseTemplateAdd(c *gin.Context) {

}

API 注释定义

参考下面连接
链接：https://www.jianshu.com/p/4875b5ac9feb

官网文档：
https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

更多参考文档：

http://www.topgoer.com/其他/Swagger.html

https://blog.csdn.net/weixin_42661321/article/details/108887918