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

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