golang gin框架 集成swagger 自动生成文档
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