Golang gin框架使用swagger生成接囗文档
0、开发环境
操作系统：Win10
Golang版本：1.15
1、安装swag
go get github.com/swaggo/swag/cmd/swag此时会在环境变量 GOBIN目录中生成swag.exe，如下图所示
验证是否安装成功
F:\Golang\TalentChain\talentchain>swag -v
swag version v1.8.12、安装依赖包
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles3、编写注解及添加访问路由
（1）导入包
package main
import (
//.....省略许多包
_ "talentchain/docs" //talentchain是工程的module名称，改成自己工程的module名
)注：必须导入docs，否则将报错： Failed to load API definition. 如下图所示：
（2）编写注解
注：注解详情可参见官网文档 Swagger Documentation
go-swapper注解规范说明
// @Summary 摘要
// @Description 描述
// @Description 接口的详细描述
// @Id 全局标识符
// @Version 接口版本号
// @Tags 接口分组，相当于归类
// @Accept json 浏览器可处理数据类型
// @Produce json 设置返回数据的类型和编码
// @Param 参数格式 从左到右：参数名、入参类型、数据类型、是否必填和注释 例：id query int true "ID"
// @Success 响应成功 从左到右：状态码、参数类型、数据类型和注释 例：200 {string} string "success"
// @Failure 响应失败 从左到右：状态码、参数类型、数据类型和注释 例：400 {object} string "缺少参数 ID"
// @Router 路由： 地址和http方法 例：/api/user/{id} [get]
// @contact.name 接口联系人
// @contact.url 联系人网址
// @contact.email 联系人邮箱
参数param的几种类型
query 形如 /user?userId=1016
body 需要将数据放到 body 中进行请求
formData multipart/form-data* 请求
path 形如 /user/1016
header header头信息
上面对基本注解进行了解释，下面在代码中增加注解
main函数添加注解
package main
import (
"github.com/gin-gonic/gin"
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"talentchain/controller"
_ "talentchain/docs"
)
// @title 人企上链接囗文档
// @version 1.0
// @description 人企上链项目
// @termsofservice https://github.com/xxxx
// @contact.name Tracy
// @contact.email [email protected]
// @host 127.0.0.1:9090
func main() {
r := gin.Default()
r.POST("/labourer/register",controller.Register)
r.Run(":9090")
}路由函数添加注解
// @Summary 个人注册
// @title Swagger API
// @version 1.0
// @Tags 劳动者管理
// @description 个人注册接囗
// @BasePath /labourer/register
// @Host 127.0.0.1:9090
// @Produce json
// @Param phone body LabourerInfo true "劳动者信息"
// @Success 200 {object} RespData "{"code":200,"data":{},"msg":"ok"}"
// @Router /labourer/register [post]
func Register(c *gin.Context) {
// to do something
}（3）添加访问路由
# 添加swagger访问路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
package main
import (
"github.com/gin-gonic/gin"
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"talentchain/controller"
_ "talentchain/docs"
)
// @title 人企上链接囗文档
// @version 1.0
// @description 人企上链项目
// @termsofservice https://github.com/xxxx
// @contact.name Tracy
// @contact.email [email protected]
// @host 127.0.0.1:9090
func main() {
r := gin.Default()
// 添加swagger访问路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.POST("/labourer/register",controller.Register)
r.Run(":9090")
}4、生成文档
swag init将会生成一个docs文件夹，下面生成3个文件，如下所示：
F:\Golang\TalentChain\talentchain>tree /F docs
文件夹 PATH 列表
卷序列号为 00000040 0CA4:1102
F:\GOLANG\TALENTCHAIN\TALENTCHAIN\DOCS
docs.go
swagger.json
swagger.yaml
注：每次添加或修改注解后，都需要使用swag init命令重新生成文档，使其生效
5、浏览器访问
启动工程，在浏览器中输入地址：http://127.0.0.1:9090/swagger/index.html
测试接囗
点击接囗右侧展开按钮
点击"Try it out"按钮
输入参数值，点击”Execute“按钮
查看响应结果
参见官网文档 Swagger Documentation