欢迎加入go语言学习交流群:636728449
go实践之swagger自动生成api文档
作为一个后端开发,给前端提供api接口是必须的。手动去写文档不是一个程序员的风格。swagger就是一个很好的api文档生成该工具,go当然也支持了。下面看看怎么使用这个工具。
1、安装需要用到的包
root@localhost github.com # go get -u github.com/swaggo/swag/cmd/swag
root@localhost github.com # swag -v
swag version v1.4.0
安装完成后检查命令是否可用,如果不行执行,请将$GOPATH/bin
加入到 $PATH
当中去。在windows中可以在下载源码后,自己编译生成swag.exe程序。后续把exe文件拷贝到项目根目录下面执行swag.exe init
也是一样的。
root@localhost github.com # go get -u github.com/swaggo/gin-swagger
root@localhost github.com # go get -u github.com/swaggo/gin-swagger/swaggerFiles
安装gin-swagger,用来集成到我们前一篇文章go实践之apiserver搭建实现的apiserver当中去。
2、接口代码支持swagger
在route生成的地方增加swagger的handler
rg.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
在api处根据api添加描述
package app
import (
"github.com/gin-gonic/gin"
"go.uber.org/zap"
"net/http"
"github.com/zhanben/go_site/tool/db"
)
type User struct {
db *db.DbConn
Logger *zap.SugaredLogger
}
func NewUser(dbConn *db.DbConn, logger *zap.SugaredLogger) (*User, error) {
user := &User{
db: dbConn,
Logger: logger,
}
return user, nil
}
func (u *User) initRouter(r *gin.RouterGroup) {
//在此添加接口
r.GET("/users", u.getAllUsers) //根据账号获取所有用户信息
r.GET("/users/:name", u.getOneUser) //根据用户名获取用户详细信息
}
// @Summary 获取所有用户
// @Produce json
// @Success 200 {string} json "{"RetCode":0,"UserInfo":{},"Action":"GetAllUserResponse"}"
// @Router /api/users [get]
func (u *User) getAllUsers(c *gin.Context) {
//构建返回结构体
res := map[string]interface{}{
"Action": "GetAllUserResponse",
"RetCode": 0,
}
sql := "select * from user limit 10"
result, err := u.db.Select(sql)
if err != nil {
u.Logger.Error("get user info from db error!")
abortWithError(u.Logger, c, err)
}
res["UserInfo"] = result
c.JSON(http.StatusOK, res)
}
// @Summary 获取单个用户
// @Produce json
// @Accept json
// @Param name path string true "Name"
// @Success 200 {string} json "{"RetCode":0,"UserInfo":{},"Action":"GetOneUserResponse"}"
// @Router /api/users/{name} [get]
func (u *User) getOneUser(c *gin.Context) {
//构建返回结构体
res := map[string]interface{}{
"Action": "GetOneUserResponse",
"RetCode": 0,
}
userName, ok :=c.Params.Get("name")
if !ok {
u.Logger.Error("parameter name must be fixed!")
}
u.Logger.Infof("get user name from url:%s",userName)
sql := "select * from user where username=?"
result, err := u.db.Select(sql,userName)
if err != nil {
u.Logger.Error("get user info from db error!")
res["RetCode"]= "-1"
res["Error"] = "user not exist!"
}else{
res["UserInfo"] = result
u.Logger.Info("get one user info successful!")
}
c.JSON(http.StatusOK, res)
}
在mian函数出添加描述
// @title Go-site Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host 127.0.0.1
// @BasePath ""
func main() {
//Read config file
err := config.ParseConfig()
if err != nil {
panic(fmt.Errorf("Failed to read config file: %s \n", err))
}
3、 生成swagger接口
在项目的根目录:windows下执行swag.exe init
,linux下执行swag init
执行完成之后会生成docs目录,里面含有自动生成的文档。
浏览器输入访问url:http://127.0.0.1:5000/api/docs/index.html,就可以打开页面了。
本文的全部的代码可以到github下载:git clone --branch swagger git@github.com:Zhanben/go_site.git