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