Mac下安装swag，并基于Golang gin框架使用swagger生成接口文档

Swagger

Swagger本质上是一种使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

swag的安装及应用

我的操作系统的：macOS

安装swag：go install github.com/swaggo/swag/cmd/swag@latest

安装命令：

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

检查安装是否成功：swag -v

swag -v
#output: swag version v1.8.12

如果遇到报错：zsh: command not found: swag
先查看一下GOPATH的目录：

go env

试一下 $GOPATH/bin/swag -v，比如$GOPATH=“/Users/xxx/go”

/Users/xxx/go/bin/swag -v
#output: swag version v1.8.12

这样的话，就是没有加到环境变量，如下添加：

vim ~/.bash_profile
export PATH=/usr/xxx/go/bin:$PATH

最后运行source ~/.bash_profile更新环境变量 或者关掉终端再打开试一试swag -v 应该就正常了。

安装依赖包：gin-swagger库

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/alecthomas/template

导入docs包：import ( _ "$本地包名/docs" )

import (
	_ "$本地包名/docs"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/files"
)

如果未导入dosc包，访问http://localhost:8080/swagger/index.html时将报错如下：

编写swag注解

注解详情可参见官网文档 Swagger Documentation

注解	描述
@Summary		摘要
@Description	接口的详细描述
@Tags 			接口分组，相当于归类
@Accept 		json 浏览器可处理数据类型
@Produce		json 设置返回数据的类型和编码，例如：json、xml、html 等等
@Param			参数格式 从左到右：参数名、入参类型、数据类型、是否必填和注释  例：id query int true "ID"
@Success		响应成功 从左到右：状态码、参数类型、数据类型和注释  例：200 {string} string "success"
@Failure		响应失败 从左到右：状态码、参数类型、数据类型和注释  例：400 {object}  string "缺少参数 ID"
@Router			路由	    从左到右分别为：路由地址，HTTP 方法  例：/api/user/{id} [get]

比如下面的UserLogin接口函数定义：

//	@Summary		用户登录
//	@Description	用户登录
//	@Tags			用户相关
//	@Accept			application/x-www-form-urlencoded
//	@Produce		json
//	@Param			username	formData	string	true	"账户名"
//	@Param			password	formData	string	true	"密码"
//	@Success		200			{object}	string
//	@Router			/login [post]
func UserLogin(c *gin.Context) {
	var user User
    if err := c.ShouldBindJSON(&user); err != nil {
        fmt.Println(err.Error())
		c.JSON(200, gin.H{
			"result": 1, 
			"msg": "fail",
		})
        return
    }
	c.JSON(200, gin.H{
		"result": 0, 
		"msg": "success",
		"data"	: "用户登录 ok",
	})
}

格式化swag注解：swag fmt

swag fmt

生成docs文档：swag init

# swai init 默认通过项目根目录下的`main.go`文件生成
swag init
# 如果`main.go`不在根目录下，需要使用参数-g指定，比如在 `main/main.go`时命令为
swag init -g ./main/main.go

该命令会在项目根目录下生成一个docs文件夹，里面有下面3个文件夹：

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

注意：每次更新注解后，都需要使用swag init重新生成文档。

添加访问路由：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

import (
	_ "$本地包名/docs"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/files"
)
r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

从浏览器访问：http://localhost:8080/swagger/index.html

启动项目，在浏览器输入：http://localhost:8080/swagger/index.html
注：ip和端口号改成自己项目的即可