Golang Gin 使用gin-swagger產生Swagger REST API文件

Go Gin 使用gin-swagger套件產生Router的REST API文件。

安裝

範例環境

• macOS
• Go 1.16
• Gin 1.7.2
• gin-swagger v1.7.0

範例專案目錄名稱為go-demo。

在命令列輸入go get -u github.com/swaggo/swag/cmd/swag下載swaggo/swag套件，gin-swagger利用該套件轉換Go annotation為Swagger文件。

~/../go-demo/$ go get -u github.com/swaggo/swag/cmd/swag
go: downloading github.com/swaggo/swag v1.7.0
go: downloading github.com/urfave/cli/v2 v2.3.0
go: downloading github.com/ghodss/yaml v1.0.0
go: downloading github.com/go-openapi/spec v0.19.14
go: downloading github.com/KyleBanks/depth v1.2.1
go: downloading golang.org/x/tools v0.0.0-20201120155355-20be4ac4bd6e
go: downloading gopkg.in/yaml.v2 v2.3.0
go: downloading gopkg.in/yaml.v2 v2.4.0
go: downloading github.com/go-openapi/spec v0.20.3
go: downloading github.com/urfave/cli v1.22.5
go: downloading github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d
go: downloading github.com/go-openapi/swag v0.19.11
go: downloading github.com/go-openapi/jsonpointer v0.19.3
go: downloading github.com/go-openapi/jsonreference v0.19.4
go: downloading github.com/cpuguy83/go-md2man/v2 v2.0.1
go: downloading github.com/go-openapi/jsonpointer v0.19.5
go: downloading github.com/go-openapi/jsonreference v0.19.6
go: downloading github.com/go-openapi/swag v0.19.15
go: downloading github.com/russross/blackfriday/v2 v2.0.1
go: downloading github.com/PuerkitoBio/purell v1.1.1
go: downloading github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e
go: downloading golang.org/x/text v0.3.4
go: downloading golang.org/x/net v0.0.0-20201110031124-69a78807bb2b
go: downloading github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578
go: downloading github.com/russross/blackfriday/v2 v2.1.0
go: downloading github.com/shurcooL/sanitized_anchor_name v1.0.0
go: downloading golang.org/x/tools v0.1.5
go: downloading github.com/mailru/easyjson v0.7.7
go: downloading golang.org/x/net v0.0.0-20210726213435-c6fcb2dbf985
go: downloading golang.org/x/text v0.3.6
go: downloading github.com/josharian/intern v1.0.0
go: downloading golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c
go get: added github.com/cpuguy83/go-md2man/v2 v2.0.1
go get: added github.com/go-openapi/jsonreference v0.19.6
go get: added github.com/go-openapi/spec v0.20.3
go get: added github.com/go-openapi/swag v0.19.15
go get: added github.com/mailru/easyjson v0.7.7
go get: added github.com/swaggo/swag v1.7.0
go get: upgraded golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3 => v0.0.0-20210726213435-c6fcb2dbf985
go get: upgraded golang.org/x/sys v0.0.0-20200116001909-b77594299b42 => v0.0.0-20210630005230-0f9fa26af87c
go get: upgraded golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e => v0.1.5

在命令列輸入go get -u github.com/swaggo/gin-swagger下載swaggo/gin-swagger套件。

~/../go-demo/$ go get -u github.com/swaggo/gin-swagger
go: downloading github.com/swaggo/gin-swagger v1.3.1
go: downloading github.com/gin-gonic/gin v1.7.3
go: downloading github.com/ugorji/go v1.1.13
go: downloading github.com/mattn/go-isatty v0.0.13
go: downloading github.com/ugorji/go/codec v1.1.13
go: downloading github.com/golang/protobuf v1.5.2
go: downloading github.com/json-iterator/go v1.1.11
go: downloading github.com/go-playground/validator v9.31.0+incompatible
go: downloading github.com/go-playground/validator/v10 v10.8.0
go: downloading github.com/modern-go/reflect2 v1.0.1
go: downloading github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd
go: downloading github.com/ugorji/go/codec v1.2.6
go: downloading github.com/ugorji/go v1.2.6
go: downloading github.com/leodido/go-urn v1.2.1
go: downloading golang.org/x/crypto v0.0.0-20210711020723-a769d52b0f97
go: downloading google.golang.org/protobuf v1.26.0
go: downloading google.golang.org/protobuf v1.27.1
go get: upgraded github.com/gin-gonic/gin v1.7.2 => v1.7.3
go get: upgraded github.com/go-playground/validator/v10 v10.4.1 => v10.8.0
go get: upgraded github.com/golang/protobuf v1.3.3 => v1.5.2
go get: upgraded github.com/json-iterator/go v1.1.9 => v1.1.11
go get: upgraded github.com/mattn/go-isatty v0.0.12 => v0.0.13
go get: added github.com/swaggo/gin-swagger v1.3.1
go get: upgraded github.com/ugorji/go v1.1.7 => v1.2.6
go get: added google.golang.org/protobuf v1.27.1

在命令列輸入go get -u github.com/swaggo/files下載swaggo/files套件。

~/.../go-demo/$ go get -u github.com/swaggo/files
go: downloading github.com/swaggo/files v0.0.0-20190704085106-630677cd5c14

在專案根目錄也就是main.go的所在目錄輸入swag init產生swagger的文件。執行時若出現找不到命令的訊息如下，則要設定PATH環境變數路徑指向$HOME/go/bin。

~/../go-demo/$ swag init
-bash: swag: command not found

在命令列輸入export PATH=$HOME/go/bin:$PATH把$HOME/go/bin路徑暫時設定到環境變數中（重開機設定會消失）。$HOME變數代表你的使用者目錄。

~/../go-demo/$ export PATH=$HOME/go/bin:$PATH

在命令列輸入echo $PATH可看到最前面的路徑/Users/<user>/go/bin即為剛設定的$HOME/go/bin。

~/../go-demo/$ echo $PATH
/Users/<user>/go/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

完成以上即可在專案目錄輸入swag init產生Swagger文件。

~/../go-demo/$ swag init
2021/08/05 22:33:19 Generate swagger docs....
2021/08/05 22:33:19 Generate general API Info, search dir:./
2021/08/05 22:33:19 create docs.go at docs/docs.go
2021/08/05 22:33:19 create swagger.json at docs/swagger.json
2021/08/05 22:33:19 create swagger.yaml at docs/swagger.yaml

注意swag init預設以main.go為一般API資訊註釋(General API info annotation)的所在，若主程式不叫main.go會出現cannot parse source files /../go-demo/main.go的錯誤，此時可加上flag --generalInfo（同-g）指定，例如一般API資訊的Go annotation是寫在http/api.go則輸入swag init -g http/api.go。

執行後可在專案根目錄下看到產生的docs資料夾，裡面有docs.go、swagger.json及swagger.yaml。

專案目錄結構：

go-demo/
├─ main.go
├─ docs/
│  ├─ docs.go
│  ├─ swagger.json
│  └─ swagger.yaml
│
├─ go.mod
└─ go.sum

使用

參考Swag annotation格式說明在Gin應用程式加上Go annotation來產生相應的Swagger文件內容。例如下面的main.go。並必須匯入"github.com/swaggo/files"、"github.com/swaggo/gin-swagger"設定Swagger頁面路徑，及匯入專案目錄下docs/的Swagger文件"abc.com/demo/docs"。

main.go

package main

import (
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"

    _ "abc.com/demo/docs"
)

// @title Gin Swagger Demo
// @version 1.0
// @description Swagger API.
// @host localhost:8080
func main() {

    router := gin.Default()

    router.Group("/demo/v1").
        GET("/hello", hello).
        GET("/hi", hi)

    url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

    router.Run()
}

// @Success 200 {string} string
// @Router /demo/v1/hello [get]
func hello(c *gin.Context) {
    c.JSON(200, "Hello - v1")
}

// @Success 200 {string} string
// @Router /demo/v1/hi [get]
func hi(c *gin.Context) {
    c.JSON(200, "Hi - v1")
}

github。

然後重新在命令列輸入swag init更新Swagger文件。這是我覺得很笨的地方，每次改動annotation都必須重新執行此命令來更新Swagger文件。

~/../go-demo/$ swag init
2021/08/05 23:42:32 Generate swagger docs....
2021/08/05 23:42:32 Generate general API Info, search dir:./
2021/08/05 23:42:32 create docs.go at docs/docs.go
2021/08/05 23:42:32 create swagger.json at docs/swagger.json
2021/08/05 23:42:32 create swagger.yaml at docs/swagger.yaml

啟動應用程式。如果有出現錯誤可能是產生的docs.go中有未加入的依賴。

~/.../go-demo/$ go run main.go
docs/docs.go:11:2: missing go.sum entry for module providing package github.com/alecthomas/template; to add:
        go mod download github.com/alecthomas/template

輸入go mod tidy下載缺少的依賴。

~/../go-demo/$ go mod tidy
go: downloading github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
go: downloading github.com/gin-contrib/gzip v0.0.1
go: downloading github.com/stretchr/testify v1.6.1
go: downloading gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f
go: downloading github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e
go: downloading gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776
go: downloading github.com/kr/text v0.2.0

解決以上後再次啟動專案。然後在瀏覽器輸入http://localhost:8080/swagger/index.html即可看到Swagger RESTful API如下。

如果覺得文章有幫助的話還幫忙點個Google廣告，感恩。

• Golang 使用swaggo產生Swagger REST API文件
• Golang 使用pre-commit搭配swaggo產生Swagger REST API文件
• Golang Swag @Param annotation格式