Gin實踐 連載八 為它加上Swagger

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

為它加上Swagger

一個好的 API's，必然離不開一個好的API文檔

要開發純手寫 API 文檔，不存在的 :=)

安裝 swag

1、go get

$ go get -u github.com/swaggo/swag/cmd/swag

若 $GOPATH/bin 沒有加入$PATH中，你需要執行將其可執行檔移動到$GOBIN下

mv $GOPATH/bin/swag /usr/local/go/bin

2、gopm get

該包有引用golang.org上的包，若無科學上網，你可以使用 gopm 進行安裝

gopm get -g -v github.com/swaggo/swag/cmd/swagcd $GOPATH/src/github.com/swaggo/swag/cmd/swaggo install

同理將其可執行檔移動到$GOBIN下

驗證是否安裝成功

$ swag -vswag version v1.1.1

安裝 gin-swagger

$ go get -u github.com/swaggo/gin-swagger$ go get -u github.com/swaggo/gin-swagger/swaggerFiles

註：三個包都有一定大小，安裝需要等一會或要科學上網

初始化

編寫API注釋

Swagger 中需要將相應的注釋或註解編寫到方法上，再利用產生器自動產生說明檔案

gin-swagger 給出的範例：

// @Summary Add a new pet to the store// @Description get string by ID// @Accept  json// @Produce  json// @Param   some_id     path    int     true        "Some ID"// @Success 200 {string} string    "ok"// @Failure 400 {object} web.APIError "We need ID!!"// @Failure 404 {object} web.APIError "Can not find ID"// @Router /testapi/get-string-by-int/{some_id} [get]

我們可以參照 Swagger 的註解規範和範例去編寫

// @Summary 新增文章標籤// @Produce  json// @Param name query string true "Name"// @Param state query int false "State"// @Param created_by query int false "CreatedBy"// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"// @Router /api/v1/tags [post]func AddTag(c *gin.Context) {

// @Summary 修改文章標籤// @Produce  json// @Param id param int true "ID"// @Param name query string true "ID"// @Param state query int false "State"// @Param modified_by query string true "ModifiedBy"// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"// @Router /api/v1/tags/{id} [put]func EditTag(c *gin.Context) {

參考的註解可見 gin-blog

產生

我們進入到gin-blog的項目根目錄中，執行初始化命令

[$ gin-blog]# swag init2018/03/13 23:32:10 Generate swagger docs....2018/03/13 23:32:10 Generate general API Info2018/03/13 23:32:10 create docs.go at  docs/docs.go

完畢後會在項目根目錄下產生docs

docs/├── docs.go└── swagger    ├── swagger.json    └── swagger.yaml

我們可以檢查 docs.go 檔案中的 doc 變數，詳細記載中我們檔案中所編寫的註解和說明

驗證

大功告成，訪問一下 http://127.0.0.1:8000/swagger/index.html， 查看 API 文檔產生是否正確

參考

本系列範例程式碼

• go-gin-example