golang整合swagger的实现以及效果
Swagger是一个在线接口文档使用工具,对查看项目接口文档特别是自己测试时有很大的用途
效果图
整体效果图:可以对接口进行分组, 并且增加注释
单个接口的效果图:会根据注释自己生成相应的参数,点击execute 可以获取返回结果
golang实现方式
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"rtp-cloud/src/controller"
_ "rtp-cloud/src/docs" //其中docs是你生成docs的路径
)
func InitApiRouters(r *gin.Engine) {
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
..........
}
实现是较简单的:
- go get -u github.com/swaggo/swag/cmd/swag 下载安装swag
- gin.Engine对象增加swagger映射
r.GET("/swagger/*any",ginSwagger.WrapHandler(swaggerFiles.Handler))
- 在方法接口上添加相应的注释
//@Tags 登陆接口
// @Summary 用户登陆接口
// @Description
// @Produce json
// @Param loginRequest body model.LoginRequest true "登陆的账号与密码"
// @Success 200 {object} model.GeneralResponse
// @Failure 500 {object} model.GeneralResponse
// @Router /front/login [post]
func Login(c *gin.Context) {
}
-
在与入口函数main.go 同级路径下执行
swag init
命令,会在同级生成一个docs 目录,会根据你的注释生成swagger启动需要读取的json文档 -
一定要注意要将docs 目录增加到路径读取的go文件中
_ "rtp-cloud/src/docs"
-
启动项目后访问 http://localhost:8080/swagger/index.html
Swagger 注释的写法
- 在main方法上进行总的配置
// @title rtp cloud
// @description rtp 的云端系统
// @host localhost:8080
- 在 controller方法上
//@Tags 登陆接口
// @Summary 用户登陆接口
// @Description
// @Produce json
// @Param loginRequest body model.LoginRequest true "登陆的账号与密码"
// @Success 200 {object} model.GeneralResponse
// @Failure 500 {object} model.GeneralResponse
// @Router /front/login [post]
- Tags 分组名
- @Title
这个 API 所表达的含义,是一个文本,空格之后的内容全部解析为 title - @Description
这个 API 详细的描述,是一个文本,空格之后的内容全部解析为 Description - @Param
参数,表示需要传递到服务器端的参数,有五列参数,使用空格或者 tab 分割,五个分别表示的含义如下:
1.参数名
2.参数类型,可以有的值是 formData、query、path、body、header,formData 表示是 post 请求的数据,query 表示带在 url 之后的参数,path 表示请求路径上得参数,例如上面例子里面的 key,body 表示是一个 raw 数据请求,header 表示带在 header 信息中得参数。
3.参数类型
4.是否必须
5.注释 - @Success
成功返回给客户端的信息,三个参数,第一个是 status code。第二个参数是返回的类型,必须使用 {} 包含,第三个是返回的对象或者字符串信息,如果是 {object} 类型,那么 bee 工具在生成 docs 的时候会扫描对应的对象,这里填写的是想对你项目的目录名和对象,例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。
三个参数必须通过空格分隔 - Failure
失败返回的信息,包含两个参数,使用空格分隔,第一个表示 status code,第二个表示错误信息 - @router
路由信息,包含两个参数,使用空格分隔,第一个是请求的路由地址,支持正则和自定义路由,和之前的路由规则一样,第二个参数是支持的请求方法,放在 [] 之中,如果有多个方法,那么使用 , 分隔。
更多注释的使用写法可以自行查阅
每次更新注释后记得 swag init
更新json文件
注意在最后部署到店铺的时候,把r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
注释掉,不要把API文档暴露给用户