目录
Swaggerswag的安装及应用安装swag：`go install github.com/swaggo/swag/cmd/swag@latest`检查安装是否成功：`swag -v`安装依赖包：gin-swagger库导入docs包：`import ( _ "$本地包名/docs" )`编写swag注解格式化swag注解：`swag fmt`生成docs文档：`swag init`添加访问路由：`r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))`从浏览器访问：http://localhost:8080/swagger/index.html
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和端口号改成自己项目的即可
推荐文章
您阅读本篇文章共花了：
发表评论