Golang開發Web API服務器，echo框架集成Swagger快速開發API文檔

之前在公司用C# + ASP.Net Core開發Web API服務器中，用到Swagger這個插件來生成API文檔覺得非常方便。

於是最近在學習golang開發Web API服務器的時候想着也集成Swagger到項目中，但是在網上找了很多文檔都是不可行的，並且還很複雜，要麼就是說一半的，寫着寫着不知道改怎麼寫了。

但是我不坑人，我接下來分享的我現在學習能夠正常使用的方法，並且這篇博文我會在後面的使用過程中，有新的總結或者解決問題的方法都會更新出來。

這是要用到的github上的Swagger包鏈接，這是一個專門針對echo框架優化的。

1.go get 項目包

這個是API文檔生成的工具
go get github.com/swaggo/swag/cmd/swag

這個是項目內導入的中間件包
go get -u github.com/swaggo/echo-swagger

先說下，這個swag工具download會自動編譯生成可執行包到 GOPATH/bin 目錄下，所以不需要我們去編譯這個工具

2.生成API文檔

控制檯切換目錄到work文件夾下，然後執行

swag init

檢查控制輸出沒有報錯，並且項目目錄會多一個docs的文件夾

3.導入需要用到的庫

import (
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
	echoSwagger "github.com/swaggo/echo-swagger"        //swagger包
	"net/http"

	_ "echo-demo/docs"      //swagger生成的api文檔包路徑
)

4.註冊中間件

func main() {
	e := echo.New()

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.Logger.Fatal(e.Start(":8080"))
}

到這裏，Swagger插件的導入其實就算差不多了，但是你會發現go run 打開http://localhost:8080/swagger/index.html會提示你

 

別慌，出現這個問題是因爲我們沒有在代碼中添加正確的註釋，標記HandlerFunc。

5.添加聲明性註釋

接下來我會添加一個路由，並且會對這個路由的HandlerFunc做好註釋

func main(){
	e := echo.New()

	// Middleware
	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.GET("/users", getUser)

	e.Logger.Fatal(e.Start(":8080"))
}

// @Title GetUser
// @Description 獲取用戶信息
// @Accept  json
// @Param nick_name formData string true "暱稱"
// @Param user_name formData string true "用戶名稱"
// @Param password formData string true "密碼"
// @Param age formData int true "年齡"
// @Success 200 "獲取信息成功"
// @Failure 400	"獲取信息失敗"
// @Router /getUser [get]
func getUser(c echo.Context) error {
	// User ID from path `users/:id`
	return c.String(http.StatusOK, "hello")
}

上面的具體備註我就不解釋了，現在可以啓動我們的服務端程序了，打開http://localhost:8080/swagger/index.html就能看到最後的效果啦。

好啦，golang + swagger 基本就是這樣了，有問題或者建議歡迎留言告訴我，有問題我會及時修正。