golang整合swagger的实现以及效果
golang整合swagger的实现以及效果Swagger是一个在线接口文档使用工具,对查看项目接口文档特别是自己测试时有很大的用途效果图整体效果图:可以对接口进行分组, 并且增加注释单个接口的效果图:会根据注释自己生成相应的参数,点击execute 可以获取返回结果golang实现方式ginSwagger "github.com/swaggo/gin-swagger""github.com/sw
·
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文档暴露给用户
更多推荐
所有评论(0)