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