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)
}
產生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頁面如下:
沒有留言:
張貼留言