Golang项目自动生成swagger格式接口文档方法（一）

swag工具介绍和安装

Swag是一款可以将Go的注释转换为Swagger2.0格式文档的工具，生成接口文档用到的注释需要按照swag要求的格式书写。

使用go install方式下载安装swag

$ go install github.com/swaggo/swag/cmd/swag@latest

也可以从github的release页面下载编译好的二进制文件，以1.8.10版本为例：

$ wget https://github.com/swaggo/swag/releases/download/v1.8.10/swag_1.8.10_Linux_x86_64.tar.gz
$ tar zxvf swag_1.8.10_Linux_x86_64.tar.gz
$ chmod +x ./swag
$ mv swag /usr/local/bin

在包含main.go文件的项目根目录运行swag init将会解析注释并生成文件（docs文件夹），修改对应注释后再次运行swag ini即可：

swag init

使用swag fmt可以格式化SWAG注释：

swag fmt

符合swag要求的API通用注释写法

在main.go的main方法添加API通用注释

// @title         account API
// @version       1.0
func main() {
    //...
}

更多通用注释字段说明和示例：

符合swag要求的具体API注释

在接口的handler方法中添加具体的API注释

// Login godoc
// @Summary		  登录
// @Schemes		  https
// @Description	          登录
// @Tags	          account
// @accept	          json
// @Produce		  json
// @Param	          account	body param.LoginReq	true	"login"
// @Success		  200		{object}	param.JSONResult{data=param.LoginRes}
// @Router	          /user/login [post]
func Login(g *gin.Context) {
    //...
}

参数注释和返回注释支持结构体，本例中用到的结构体在param包下面，内容如下

// JSONResult response body结构
type JSONResult struct {
    Code int         `json:"code" binding:"required"`
    Data interface{} `json:"data" binding:"required"`
    Msg  string      `json:"msg" binding:"required"`
}

// LoginReq 登录接口入参
type LoginReq struct {
    Email     string  `json:"email" binding:"required,min=6,max=50"`     // 邮箱
    Password  string  `json:"Password" binding:"required,min=8,max=15"`  // 密码
}

// LoginRes 登录接口返回参数
type LoginRes struct {
    Token json:"token"` // token
}

更多注释字段说明：

生成接口文档

按照swag要求写好注释后，执行如下命令生成文档

swag init

会在根目录生成docs文件夹，里面包含swagger.json,、swagger.yaml和doc.go三个文件。

swag的使用方法比较简单直观，更多信息可以参考https://github.com/swaggo/swag/blob/master/README_zh-CN.md。