goswagger/gin-swagger使用

goswagger使用 gin-swagger用法

https://github.com/swaggo/swag

gin-swagger使用方法

1. 首先下载安装swag命令

//go版本1.16之前使用该命令
go get -u github.com/swaggo/swag/cmd/swag

//go版本1.16版本以及之后的版本使用该命令
go install github.com/swaggo/swag/cmd/swag@latest

2. 执行 swag init 命令生成 docs文件夹

//保证执行命令的位置与main.go在同一文件夹
swag init

//如果没有写main.go文件，可以使用 -g来指定 写有swagger通用api信息的文件路径
swag init -g http/api.go

执行swag init之后会生成一个文件夹 doc
查看doc/doc.go是否有问题，目前存在一个问题，是当swag 的版本是1.7.9时，执行swag init，会出现冲突可以参考：https://github.com/swaggo/swag/issues/1126

解决方法：安装预编译版本并下载另外一个包

go get github.com/swaggo/echo-swagger
go install github.com/swaggo/swag/cmd/swag@v1.7.9-p1

//如果还是不行
 go get github.com/alecthomas/template

3. gin的内置配置

swag init 指定的文件就是包含了以下swagger通用注释的文件

导入相关的包以及加入swagger的路由：

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files


// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [e-mail]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth
func main() {
    r := gin.Default()

    c := controller.NewController()

    v1 := r.Group("/api/v1")
    {
        accounts := v1.Group("/accounts")
        {
            accounts.GET(":id", c.ShowAccount)
            accounts.GET("", c.ListAccounts)
            accounts.POST("", c.AddAccount)
            accounts.DELETE(":id", c.DeleteAccount)
            accounts.PATCH(":id", c.UpdateAccount)
            accounts.POST(":id/images", c.UploadAccountImage)
        }
    //...
    }
    //加入swagger的路由，可以支持在页面访问
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

除了导入以上 ginSwagger “github.com/swaggo/gin-swagger”、swaggerFiles "github.com/swaggo/gin-swagger/swaggerFiles"两个包，还要将swag init的doc包导入进来，并可以对doc包里的内容进行修改

doc.go

var SwaggerInfo = &swag.Spec{
	Version:          "1.0",
	Host:             "localhost:9090",
	BasePath:         "",
	Schemes:          []string{},
	Title:            "qingzhu-swagger",
	Description:      "qingzhu swagger 示例项目",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate_swagger,
}

func init() {
	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}

4. 对接口进行增加注释解释

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200
// @Router /log/:id [get]
func ReadLokiLog(ctx *gin.Context) {
	//jobname := "dtuic-newdtuic-default-f7bjg/dtuic-newdtuic-default-new-dtuic-deploy-szx9q"
	hh := ctx.Param("id")
	atoi, _ := strconv.Atoi(hh)
	fmt.Println(atoi)
	c, err := upgrader.Upgrade(ctx.Writer, ctx.Request, nil)
	if err != nil {
		log.Print("upgrade:", err)
		return
	}
}

相关注释可以参考：https://github.com/swaggo/swag/blob/master/README_zh-CN.md#通用api信息

5. 启动项目进行查看

执行 swag init 刷新 doc文件

启动服务，访问页面 http://localhost:9090/swagger/index.html,查看相关注释是否生效

6. 对与第四点的注释位置，其实对于函数位置其实是无所谓的，你注释写在什么方法上都行，因为在生成swagger文件的时候，是根据你指定的包去扫描的，去扫描这个包里面的go文件，上面的func是否有相关注释，有注释，就能当成一个api，所以并不仅仅限制于 func(ctx *gin.context) 这样的函数，写在handle函数上面是为了方便于handle一一对应，对于程序员来说方便寻找，以及方便修改接口的同时修改swagger

7. swagger的核心就是，获取项目的swagger api信息，将swagger信息通过项目路由出去

swagegr与其他web项目的结合也就是为了方便路由，对于获取项目的swagger api 可以使用注释以及 swag init命令的形式获取swag init命令的详细使用如下：

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")