golang gin框架 集成swagger 自动生成文档

Posted 2022-09-11 tsxylhs

goswagger github仓库

https://github.com/swaggo/swag

 

安装 swag cli

1.因为网络原因，先安装gopm 管理工具

go get -v -u github.com/gpmgo/gopm

 

安装到了 $GOPTH/bin里 找不到的话，用 sudo find / -name gopm 找一下

2.安装swag

gopm get -g -v github.com/swaggo/swag/cmd/swag

过程中可能会报错，重试即可

3.找到 swag （ find / -name swag ====》   cd /go/src/github.com/swaggo/swag/cmd/swag/） 会看到main.go 文件

4 执行：go install (可能会报错缺少包，挨个安装 go get -u  github.com/urfave/cli)

5 再次执行  go install 

不出意外的话，swag安装成功了

找到swag执行文件，应该在$GOPTH/bin里面，然后加成全局变量（ sudo cp swag /usr/local/go/bin/）

然后试一下swag -version

lhs:redigo houlv$ swag -version
swag version v1.6.2

成功！

在golang-gin项目上集成swagger

找到main函数所在的类

添加以下代码

 

import里

swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "testsu.cn/rocket/docs"

其中docs是你生成docs的路径

面函数里实现

    g.Go(func() error 
        r := gin.New()
        url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
        r.Run()
        return nil
    )

 

go.mod里添加

	github.com/swaggo/gin-swagger v1.2.1-0.20190717074206-d488a692749f
	github.com/swaggo/swag v1.5.1

 在API handler文件里添加标准注解

例如：

// @Summary 生成pdf文档
// @Description 传递id生成pdf文档
// @Accept json
// @Param id path int true "id"
// @Success 200 object model.VersionDTO
// @Failure 500 string json ""code":500,"data":,"msg":"ok""
// @Router /report/id/pdf/download [get]
func (handler *TestcaseReporthtml) DownloadTestCasePDF(c *gin.Context) 

然后在项目的根目录执行 

swag init -g launcher/api-rocket/web.go 

 

 -g 后面所跟的为main方法在的位置

 

之后将项目跑起来，访问地址：
http://localhost:8080/swagger/index.html

即可看到自动生成的文档

入截图所示：

 

 

最后添加：将swagger的标准库添加上：

标准注释

https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html