@[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