中年大叔学编程-Gin-Swagger生成API接口文档
最近简单的学习了一下Golang，并且用Gin开发了两个小应用，一个短域名生成，一个微信小程序。感受到了Golang的代码简洁、部署简单、内存占用少、零停机平滑重启等优势。在开发小程序的时候，需要生成接口文档，这里需要用到Gin-Swagger了，所以简单的就来整理一下。
这里我用的环境是：
- go version go1.14.6 windows/amd64
- GoLand 2020.2.1
- gin v1.6.3
- swag v1.6.7
这里先用Goland新建一个demo项目吧,在新建的时候，我们最好就要把包的代理地址配置好
这里我们需要安装Gin、swag、gin-swagger、files几个包，可以通过命令的方式
go get -u github.com/gin-gonic/gin
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
但是在Goland中，会自动获取复制的连接，然后提醒安装，直接点击相应的按钮即可，非常方便。 这里我们新建一个main.go文件，加入如下代码
import (
_ "GinDemo/docs"
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
func main() {
r := gin.New()
// use ginSwagger middleware to
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run()
}
然后进入Terminal中执行swag init
现在，运行项目(默认8080端口)并访问
http://localhost:8080/swagger/index.html
因为现在还没有开发相应的接口，所以什么信息都没有，在开始之前，我们需要先了解一下gin-swagger的注解
- @Tags 接口分组，相当于归类
- @Summary 接口的简要描述
- @Description 接口的详细描述
- @Id 全局标识符
- @Version 接口版本号
- @Accept 发起请求的数据类型
- @Produce 接口返回的数据类型
- @Param 请求参数描述
- @Success 请求成功后返回信息
- @Failure 请求失败后返回信息
- @Router 请求的路由路径和请求方式。
- @contact.name 接口联系人
- @contact.url 联系人网址
- @contact.email 联系人邮箱
上面就是一些较为基础的参数说明，当然还有一些更加复杂的，比如@security,@in等，这些以后再说吧，我们就可以在相应的Controller方法上加注解了
// @Tags Demo
// @Id 1
// @Summary 接口Demo
// @Description 接口详细描述信息
// @Produce json
// @Param id path int true "ID"
// @Success 200 {string} string
// @Failure 400 {string} string
// @Router /api/v1/demo/{id} [get]
// @contact.name 中年大叔学编程
// @contact.email eyiadmin@163.com
func Demo(c *gin.Context) {
c.JSON(200,"OK!")
}
在main方法中注册路由
r.GET("/api/v1/demo/:id", controller.Demo)
现在，进入Terminal中再次执行swag init并启动，这时候就可以看到对应的内容了
我们来执行以下看看效果
这样一个API接口文档就有了，而且还方便我们调试。
我只是记录我的学习过程，由于书读得少，可能很多地方表述或者是理解得不对，请轻喷并指正。