引言
- 接口文档是项目中非常重要的一个环节
- 如何维护接口文档是绝大部分开发人员都遇到过的问题（很头疼）
- 编写注解或通过扫描代码生成注解，就能生成统一标准的接口文档和一系列Swagger工具
- 今天我带着大家学习如何在gin项目中使用Swagger生成接口文档
- github代码地址
1、安装swag
go get github.com/swaggo/swag/cmd/swag
将在GOPATH/bin/swag 移动到全局$GOBIN目录下,校验是否安装成功
swag -v
2、安装gin-swagger
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles
3、api编写注解并生成
gin-swagger 的注解规范
// @Summary 摘要
// @Description 描述
// @Description 接口的详细描述
// @Id 全局标识符
// @Version 接口版本号
// @Tags 接口分组，相当于归类
// @Accept json 浏览器可处理数据类型
// @Produce json 设置返回数据的类型和编码
// @Param 参数格式 从左到右：参数名、入参类型、数据类型、是否必填和注释 案例：id query int true "ID"
// @Success 响应成功 从左到右：状态码、参数类型、数据类型和注释 案例：200 {string} string "ok"
// @Failure 响应失败 从左到右：状态码、参数类型、数据类型和注释 案例：400 {object} web.APIError "We need ID!!"
// @Router 路由： 地址和http方法 案例：/testapi/get-string-by-int/{some_id} [get]
// @contact.name 接口联系人
// @contact.url 联系人网址
// @contact.email 联系人邮箱
param有几种类型
- query 形如 /user?username=Jack&age=18
- body 需要将数据放到 body 中进行请求
- formData multipart/form-data* 请求
- path 形如 /user/1
- header 在header头
tool新增api返回
type JSONRET struct {
Error_code int `json:"error_code"`
Msg string `json:"msg"`
Data interface{} `json:"data"`
}
func JSONP(c *gin.Context, code int, msg string, data interface{}) {
h := JSONRET{
code, GetMsg(code, msg), data,
}
c.JSONP(200, h)
}
app/models/user.go新增返回结构体 （便于接口文档返回具体字段）
type UserSwagger struct {
Lists []*User
Total int
}
控制器添加文档注解
// @Summary 用户列表
// @Produce json
// @Failure 400 {object} tool.JSONRET "参数错误"
// @Failure 20001 {object} tool.JSONRET "Token鉴权失败"
// @Failure 20002 {object} tool.JSONRET "Token已超时"
// @Failure 20004 {object} tool.JSONRET "Token错误"
// @Failure 20005 {object} tool.JSONRET "Token参数不能为空"
// @Success 0 {object} models.UserSwagger "查询成功"
// @Router /api/v1/users [get]
添加项目注解 在main.go
// @title go-api 框架
// @version 1.0
// @description gin-web框架
// @termsofservice https://github.com/18211167516/Go-Gin-Api
// @contact.name baichonghua
// @contact.email 18211167516@163.com
// @host 127.0.0.1:8080
最后执行命令生成文档，会生成docs目录
swag init
4、添加访问接口文档路由
注意点要引入 当前项目docs，否则会报错 Failed to load spec.
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
5、查看文档验证
http://127.0.0.1:8080/swagger/index.html
到这里我们成功的使用swagger生成了项目api文档
- 相关文档
- gin-swagger
- swager-go
