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

文章目录

• go实践之swagger自动生成api文档
• 1、安装需要用到的包
• 2、接口代码支持swagger
• 3、 生成swagger接口

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