go实践之swagger自动生成api文档

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

文章目录

go实践之swagger自动生成api文档

1、安装需要用到的包
2、接口代码支持swagger
3、生成swagger接口

作为一个后端开发，给前端提供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 appimport ( "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)) }