中年大叔学编程-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接口文档就有了，而且还方便我们调试。

我只是记录我的学习过程，由于书读得少，可能很多地方表述或者是理解得不对，请轻喷并指正。