七叶笔记 » golang编程 » 中年大叔学编程-Gin-Swagger生成API接口文档

中年大叔学编程-Gin-Swagger生成API接口文档

分类: golang编程 | 浏览: 200

最近简单的学习了一下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端口)并访问

因为现在还没有开发相应的接口，所以什么信息都没有，在开始之前，我们需要先了解一下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接口文档就有了，而且还方便我们调试。

相关文章