網頁

▼

2022/1/25

Golang 使用swaggo產生Swagger REST API文件

Go Web server使用swaggo/swag產生REST API文件。


注意swag和go-swagger是兩個不同的套件，這是剛學習Go的swagger套件時容易搞混的地方，不過目的皆是生成REST API的swagger文件(swagger.yaml)。差別在swag會在應用程式中產生swagger文件及Swagger UI，使用上較簡便；go-swagger僅產生swagger文件，但可以依Swagger REST API規格產生Server、Client、Model程式碼。


範例環境：

  • Go 1.17


建立Go Web專案

參考「Golang 建立網頁伺服器」建立一個Web專案，並把GET|/hello的handler提取出來為HelloHandler()函式。

main.go

package main

import (
    "fmt"
    "net/http"
)

func main() {
    http.HandleFunc("/hello", HelloHandler)

    http.ListenAndServe(":8080", nil)
}

func HelloHandler(rw http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    content := fmt.Sprintf("hello, %s", name)
    fmt.Fprint(rw, content)
}

安裝swaggo套件

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

~/../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 1.16以後要輸入go install github.com/swaggo/swag/cmd/swag。

輸入swag --version檢視版本確認安裝成功。

~/../go-demo$ swag --version
swag version v1.7.0

此外專案還需要安裝swaggo/http-swagger套件將swagger文件轉成REST API頁面。執行go get -u github.com/swaggo/http-swagger下載。

~/../go-demo$ go get -u github.com/swaggo/http-swagger
go: downloading github.com/swaggo/http-swagger v1.2.0
go: downloading github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2
go: downloading golang.org/x/tools v0.1.8
go: downloading golang.org/x/net v0.0.0-20220121210141-e204ce36a2ba
go: downloading golang.org/x/sys v0.0.0-20220114195835-da31bd327af9
go get: upgraded github.com/mailru/easyjson v0.7.6 => v0.7.7
go get: added github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2
go get: added github.com/swaggo/http-swagger v1.2.0
go get: upgraded golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d => v0.0.0-20220121210141-e204ce36a2ba
go get: upgraded golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e => v0.0.0-20220114195835-da31bd327af9
go get: upgraded golang.org/x/tools v0.1.7 => v0.1.8


撰寫API註釋

參考Swag annotation註釋說明在應用程式加上Go annotation來產生相應的Swagger文件內容。

在main.go的main()上方撰寫一般的API資訊註釋(General API Info annotation)；在handler HelloHandler()撰寫API操作資訊註釋(API Operation)。

匯入github.com/swaggo/http-swagger及專案目錄docs/中的Swagger文件abc.com/demo/docs。

最後設定swagger文件的路徑為GET|/swagger/，並交由httpSwagger.WrapHandler將swagger文件包成REST API頁面返回。

main.go

package main

import (
    "fmt"
    "net/http"

    _ "abc.com/demo/docs"
    httpSwagger "github.com/swaggo/http-swagger"
)

// @contact.name   菜鳥工程師肉豬
// @contact.url    https://matthung0807.blogspot.com/
// @title Swagger Demo
// @version 1.0
// @description Swagger API.
// @host localhost:8080
func main() {
    http.HandleFunc("/hello", HelloHandler)
    http.HandleFunc("/swagger/", httpSwagger.WrapHandler)

    http.ListenAndServe(":8080", nil)
}

// @Tags Hello
// @Produce plain
// @Param name query string false "user name"
// @Success 200 {string} string "ok"
// @Router /hello [get]
func HelloHandler(rw http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    content := fmt.Sprintf("hello, %s", name)
    fmt.Fprint(rw, content)
}

github。


產生REST API文件

在專案根目錄輸入swag init產生Swagger文件。

~/../go-demo$ swag init
2022/01/25 15:47:37 Generate swagger docs....
2022/01/25 15:47:37 Generate general API Info, search dir:./
2022/01/25 15:47:37 create docs.go at docs/docs.go
2022/01/25 15:47:37 create swagger.json at docs/swagger.json
2022/01/25 15:47:37 create swagger.yaml at docs/swagger.yaml

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

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

由於產生的docs.go中有引入外部套件，所以在根目錄輸入go mod tidy下載依賴的套件。

~/../go-demo$ go mod tidy
go: finding module for package github.com/swaggo/swag
go: finding module for package github.com/alecthomas/template
go: downloading github.com/swaggo/swag v1.7.8
go: found github.com/alecthomas/template in github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
go: found github.com/swaggo/swag in github.com/swaggo/swag v1.7.8
go: downloading github.com/go-openapi/spec v0.20.4
go: downloading golang.org/x/tools v0.1.7
go: downloading github.com/otiai10/copy v1.7.0
go: downloading github.com/agiledragon/gomonkey/v2 v2.3.1
go: downloading golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d
go: downloading github.com/mailru/easyjson v0.7.6


開啟REST API文件

啟動專案並在瀏覽器輸入http://localhost:8080/swagger/index.html進入Swagger UI REST API頁面如下：




沒有留言:

張貼留言