Gin框架集成Swagger

# 一、安装客户端命令

官方地址: https://github.com/swaggo/gin-swagger

# 1.17版本之前 安装命令
go get -u github.com/swaggo/swag/cmd/swag
# 1.17+版本直接安装swag 命令
go install github.com/swaggo/swag/cmd/swag@latest

1
2
3
4

# 二、初始化

# 安装没有问题会在项目根目录下生成以下目录(docs/doc.go)
swag init

2023/08/18 10:30:07 Generate swagger docs....
2023/08/18 10:30:07 Generate general API Info, search dir:./
2023/08/18 10:30:48 create docs.go at docs/docs.go
2023/08/18 10:30:48 create swagger.json at docs/swagger.json
2023/08/18 10:30:48 create swagger.yaml at docs/swagger.yaml

1
2
3
4
5
6
7
8

# 三、安装gin-swagger

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

1
2

# 四、配置

# 4.1 入口配置

// main包导入 docs目录
_ "gitee.com/zhengzhou-tangxin-information/gin-shsj-exe/docs"

1
2

# 4.2 路由层配置

swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"

1
2

# 4.3 访问配置

需要把swagger相关通过路由暴露出去，这样可以直接访问

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

::: deatils 完整示例

import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	
	"github.com/tchuaxiaohua/jenkins-import/routers/jenkins"
	"github.com/tchuaxiaohua/jenkins-import/svc"
)

// JenkinsRouter jenkins项目路由
func JenkinsRouter(r gin.IRouter, appCtx *svc.AppService) {
	r.GET("/jenkins/config", jenkins.JksGetConfig(appCtx))
	r.POST("/jenkins/config", jenkins.UpdateJksJobConfig(appCtx))
	r.GET("/jenkins/jobs", jenkins.JksGetJobs(appCtx))
	r.POST("/jenkins/job/import", jenkins.JksJobImport(appCtx))
}

func InitRouter(appCtx *svc.AppService) *gin.Engine {
	r := gin.Default()
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	// jenkins 路由注册
	JenkinsRouter(r, appCtx)
	return r
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

:::

# 五、路由函数注释

# 5.1 入口配置

main包中添加通用的API注释信息

package main

import (
	"github.com/tchuaxiaohua/jenkins-import/routers"
	"github.com/tchuaxiaohua/jenkins-import/svc"

	_ "github.com/tchuaxiaohua/jenkins-import/docs"
)

// @title Jenkins Job 迁移
// @version 0.1
// @description http://127.0.0.1:8080/
// @BasePath /
func main() {
	// 待优化 只需加载配置即可
	appCtx := svc.NewAppService()
	g := routers.InitRouter(appCtx)
	g.Run()
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

注意: _ "github.com/tchuaxiaohua/jenkins-import/docs" 需要导入，否则访问时会出错，因为有些静态资源都在该包目录下面

# 5.2 GET请求

// JksGetConfig 获取指定job配置
// @Summary 获取Jenkins Job配置
// @Description 通过Param参数获取指定Jenkins Job配置
// @Tags Jenkins job config
// @Accept json
// @Param jobId query string true "Jenkins Job名称"
// @Param parentFolders query string false "Jenkins Job所在文件夹路径"
// @Param jksType query string true "new/old"
// @Success 200  string   "Jenkins 配置信息"
// @Router /jenkins/config [get]
func JksGetConfig(svcJks *svc.AppService) gin.HandlerFunc {
	return func(c *gin.Context) {
		// 获取参数参数 parentId folderName childId jobName
		jobId := c.Query("jobId")
		queryData := c.Query("parentFolders")
		jksType := c.Query("jksType")
		var parentFolder []string
		if queryData == "" {
			parentFolder = nil
		} else {
			parentFolder = strings.Split(queryData, ",")
		}
		reqData := jenkins.NewJenkinsJobBase(jobId, parentFolder)
		reqData.JksType = jksType
		jksCfg, err := svcJks.AppJks.GetJksConfig(c, reqData)
		if err != nil {
			fmt.Println("获取jobs实例", err)
		}
		c.String(200, jksCfg)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 5.3 POST请求

// JksJobImport 迁移job
//
//	@Summary		迁移Jenkins Job
//	@Description	通过json参数把旧Jenkins实例job迁移至新Jenkins实例
//	@Tags			Jenkins job 迁移
//	@Accept			json
//	@Param			req	body	jenkins.JenkinsImportReq	true	"job迁移请求参数"
//	@Success		200	string	"success"
//	@Router			/jenkins/job/import [post]
func JksJobImport(svcJks *svc.AppService) gin.HandlerFunc {
	return func(c *gin.Context) {
		// 获取参数参数
		reqJKsData := jenkins.NewJenkinsImportReq()
		if err := c.ShouldBindJSON(&reqJKsData); err != nil {
			c.AbortWithStatusJSON(200,
				gin.H{
					"code": http.StatusBadRequest,
					"msg":  "jobs 请求参数绑定失败",
				})
		}
		jksRes, err := svcJks.AppJks.JksJobImport(c, reqJKsData)
		if err != nil {
			fmt.Println("jenkins job迁移失败", err)
			c.AbortWithStatusJSON(200,
				gin.H{
					"code": http.StatusBadRequest,
					"msg":  err,
				})
		}
		c.JSON(200, gin.H{
			"code": http.StatusOK,
			"msg":  "jobs 迁移成功",
			"data": gin.H{
				"jobName": reqJKsData.JobId,
				"jobUrl":  jksRes,
			},
		})
	}
}