go-swagger安装与使用

Golang 环境下使用 swagger

1.安装swagger工具

全局环境安装 swagger-go工具

# 工具安装
go install github.com/swaggo/swag/cmd/swag@latest
# 依赖源安装
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2.初步使用Swagger

swag初始化 默认生成文件./docs/

swag init

main.go 中匿名引入包 “YouGoModName/docs”

路由集成 需要在路由中配置我们的swagger

例如：下面这段代码

1. 初始化使用：在项目目录使用命令 swag init
2. 使用注解：

//	@Summary	创建文章
//	@Produce	json
//	@Param		user_name	body		string	true	"账号"
//	@Param		password	body		string	true	"密码"
//	@Param		email		body		string	false	"邮箱"
//	@Param		nick_name	body		int		false	"昵称"
//	@Success	200			{object}	Article	"成功"
//	@Failure	400			{object}	string	"请求错误"
//	@Router		/api/v1/user/register [post]
func UserRegister(c *gin.Context) {
	var userRegisterService service.UserService
	err := c.ShouldBindJSON(&userRegisterService)
	if err != nil {
		fmt.Println(err)
		c.JSON(400, "注册接口数据格式错误")
	} else {
		res := userRegisterService.Register(c.Request.Context())
		c.JSON(200, res)
	}
}

3. 路由组配置sawgger

func NewRouter() *gin.Engine {
	r := gin.Default()

	r.Use(middleware.Cors())

	// 公共路由组
	publicGroup := r.Group("")
	publicGroup.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	// V1管理路由组
	v1 := r.Group("api/v1")
	{
		v1.GET("ping", func(c *gin.Context) {
			c.JSON(http.StatusOK, "Success")
		})

		// 用户操作
		v1.POST("user/register", api.UserRegister)
	}

	return r
}

4. 使用 swag fmt 格式化我们的注解信息
5. 使用 swag init 重新加载生成我们的注解对应doc文件。
6. 启动项目，点击：Swagger UI 就可以看到我们的配置是否成功运行了。