go gin 集成swagger

1，首先在项目的根目录下执行已下命令下载安装所需依赖包

go get -u github.com/swaggo/swag/cmd/swag  #这个-u参数会将依赖包下载下来并且将其二进制程序安装在gopath/bin里，这里提前请将此目录加入环境变量，以免在执行swag init -g .\main\main.go时报找不到命令
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/gin-swagger/swaggerFiles

 

2，在router初始化的地方加入下面的一行代码：

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

例如我的如下：

 

 

3，添加注释用于生成swagger.json的信息，api文档接口信息

1）gin server实例化函数的上面加如下信息

// @title goweb project
// @version 1.0
// @description this is goweb server.
// @host 127.0.0.1:8888
// @BasePath /api/v1
func NewGinHttpServer() {

    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    v1 := r.Group("/api/v1")
    {

        v1.GET("/messages", getMessages)
        v1.POST("/addMessage", addMessage)
        v1.PUT("/updateMessage", updateMessage)
        v1.DELETE("/delMessage", delMessage)
    }
    r.Run(fmt.Sprintf(":%v", 8888))

}

2）handler上面加如下信息：

// @Summary 获取消息列表数据
// @Description get all messages
// @Accept  json
// @Produce json
// @Success 200 {string} string "success"
// @Router /messages [get]
func getMessages(c *gin.Context) {

    var m Message
    m = Message{}
    var msgs = m.GetMessageList()
    datas, _ := json.Marshal(msgs)
    fmt.Fprint(c.Writer, string(datas))

}

4，在 项目的根目录下（必须是根目录下）执行如下命令（这里必须指明main.go的位置如果main.go不在当前根目录下）

因为我之前按照网上好多例子中的尝试在main,go所在目录执行，结果是swagger.json里的内容是空的，没有将接口信息添加进去

我的目录结构是：

D:\workfile\goweb

├─.idea

│  └─httpRequests

├─bingfa

├─docs

├─main

├─mkdirtest

└─service

执行以下命令

swag init -g .\main\main.go

会在根目录下自动生成docs目录及swagger所需文件（有3个文件docs.go，swagger.json，swagger.yaml）

5，将docs目录引入到router所在的go文件中去

例如我的ipmort内容如下：

import (
    "encoding/json"
    "fmt"
    "github.com/gin-gonic/gin"
    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    "io/ioutil"
    _"web/docs"
)

其中web/docs就是docs的包目录，那个web是因为我生成mod时起的是这个名字，所以后面所有的包因为也会以这个开头，而不会以真实目录开头，我的真实目录是D:\workfile\goweb

可以看看我的mod文件的内容：

module web

go 1.15

require (
    github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
    github.com/cpuguy83/go-md2man/v2 v2.0.0 // indirect
    github.com/gin-gonic/gin v1.6.3
    github.com/go-openapi/spec v0.20.1 // indirect
    github.com/go-openapi/swag v0.19.13 // indirect
    github.com/go-sql-driver/mysql v1.5.0
    github.com/russross/blackfriday/v2 v2.1.0 // indirect
    github.com/swaggo/gin-swagger v1.3.0
    github.com/swaggo/swag v1.7.0
    golang.org/x/net v0.0.0-20210119194325-5f4716e94777 // indirect
    golang.org/x/text v0.3.5 // indirect
    golang.org/x/tools v0.1.0 // indirect
    gopkg.in/gcfg.v1 v1.2.3
    gopkg.in/warnings.v0 v0.1.2 // indirect
    gopkg.in/yaml.v2 v2.4.0
)

 至此gin集成swagger就完成了 ，我们可以启动项目验证下：

在浏览器输入：http://localhost:8888/swagger/index.html