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 基本就是这样了，有问题或者建议欢迎留言告诉我，有问题我会及时修正。