@[toc]
前言
以二开滴滴的夜莺监控作示例，说明go-swagger的简单使用
1. 安装go-swagger
-
下载地址
https://github.com/go-swagger/go-swagger/releases -
安装
解压缩后的二进制文件放到/usr/bin目录，或者放到合适的地方配置环境变量，或者做软链接都可以
2. swager 设置
2.1 main函数前的注释
在 main函数前添加如下内容
// @title magicube
// @version 1.0
// @description monitor
// @termsOfService [http://swagger.io/terms/](http://swagger.io/terms/)`
// @contact.name cloud_user
// @contact.url [http://www.swagger.io/support](http://www.swagger.io/support)`
// @contact.email support@swagger.io`
// @BasePath /
func main() {
......
}
2.2 设置路由
import (
"fmt"
"os"
"github.com/gin-contrib/gzip"
"github.com/gin-contrib/pprof"
"github.com/gin-gonic/gin"
"github.com/didi/nightingale/v5/config"
_ "github.com/didi/nightingale/v5/docs"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
func configRoutes(r *gin.Engine) {
......
r.GET("/swagger/*any", ginSwagger.DisablingWrapHandler(swaggerFiles.Handler,"on"))
......
}
注意：夜莺引用的是自己写的
docs包，如果我们直接用gin框架的话，需要引用：
import (
......
_ "testmysql/docs"
)
2.3 为swager输出示例定义结构体
后边
@Success和@Failure定义了接口正确输出和错误输出的示例，我们为其分别定义一个结构体
我们创建一个文件：pkg/imodel/imodel.go，添加代码如下：
package imodel
type SuccessRespMsg struct {
Dat interface{} `json:"dat"`
Err string `json:"err"`
}
type failRespMsg struct {
Dat interface{} `json:"dat"`
Err string `json:"err"`
}
3. 夜莺登陆接口
因为很多接口需要登陆才可以调用到，所以必须先在swager中写好登陆接口
3.1 找到登陆接口调用的函数
- 找到登陆接口
guest := r.Group("/api/n9e")
{
......
guest.POST("/auth/login", loginPost)
.......
}
- 通过登陆接口找到其调用函数
3.2 添加内容
在端口调用函数前添加如下内容
type UserModel struct {
Id int64 `json:"id"`
Username string `json:"username"`
Nickname string `json:"nickname"`
Password string `json:"-"`
Phone string `json:"phone"`
Email string `json:"email"`
Portrait string `json:"portrait"`
Status int `json:"status"`
RolesForDB string `json:"-" xorm:"'roles'"` // 这个字段写入数据库
RolesForFE []string `json:"roles" xorm:"-"` // 这个字段和前端交互
CreateAt int64 `json:"create_at"`
CreateBy string `json:"create_by"`
UpdateAt int64 `json:"update_at"`
UpdateBy string `json:"update_by"`
}
// @Summary user login
// @Description user login
// @Accept json
// @Produce json
// @Param _ body loginForm true "login Form"
// @Success 200 {object} imodel.SuccessRespMsg{dat=UserModel}
// @Failure 500 {object} imodel.failRespMsg
// @Router /api/n9e/auth/login [post]
func loginPost(c *gin.Context) {
......
}
说明：
- @Success 和 @Failure 这里使用了 “3.” 中定义的结构体
dat=UserModel 中 UserModel 即是swager输出中 dat 下的结构体- 登陆接口返回的dat 值本来是 models/user 这个结构体，但是有成员类型不是标准的go类型，swager init时会报错，因此我们去掉这个成员，重新写一个
UserModel的结构体。因为我也没想出更好的办法～～
3.3 初始化
在main函数的同级目录下执行初始化命令
swagger init
如果要看到3.4 中的结果，这里必须执行一下
也可以参考后边的6. 生成swagger接口
3.4 在swap上显示
说明：我们上边添加的内容，以后会在swap的页面中显示如下（虽然现在看不到）：
image.png
image.png
4. service-trace 接口
以二开的service-trace 接口说明一个简单的使用示例
- 在接口函数前添加如下内容
// @Tags 第三方组件
// @Summary service-trace
// @Description service trace get
// @Accept json
// @Produce json
// @Success 200 {object} imodel.SuccessRespMsg{dat=string}
// @Failure 500 {object} imodel.failRespMsg
// @Router /api/n9e/config/service-trace [get]
func serviceTraceGet(r *gin.Context) {
c := config.Config
if strings.ToLower(c.ServiceTrace.Access) == "1" {
renderData(r,c.ServiceTrace.Addr, nil)
return
}
}
说明：@Tags会在swager页面给接口分组。
image.png
5. 注册swag相关路由
- 夜莺代码在
http/rooter.go中添加如下内容
func configRoutes(r *gin.Engine) {
r.GET("/swagger/*any", ginSwagger.DisablingWrapHandler(swaggerFiles.Handler,"on"))
......
}
- 此时需要引用swaggo包
import (
......
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
6. 生成swagger接口
- 初始swagger接口化命令
swag init -g main.go ./http/*.go ./docs
说明
./http/*.go是指明swager 里配置的接口所在的文件,这个必须写，否则swager页面看不到调用http包中的函数的接口
./docs指明生成docs目录的位置
-
写入makefile
在makefile文件中添加入下内容
swag:
swag init -g main.go ./http/*.go ./docs
以后修改swager注释后执行入下命令重新初始化
# make swag
7. swager页面
url: http://IP:8000/swagger/index.html
image.png
参考文档：
https://www.jb51.net/article/195124.htm
https://studygolang.com/articles/29157?fr=sidebar
https://www.jianshu.com/p/3af6665a716b
网友评论