gin框架之用swagger自动生成API文档

• 2020 年 3 月 13 日
• 筆記

这篇文章我们讲解swagger的使用

我们在工作当中经常需要用到接口文档，那么怎么写接口文档呢？又会遇到哪些坑呢？刚开始的时候，我们用word写文档，后来我们用markdown写文档。但是这些方式不利于维护，到后来我们发现，接口改了，文档还是原来的样子，不利于维护。而且每次我们都需要用postman工具进行接口开发测试，及其繁琐麻烦。我在无意当中发现了swagger，从此喜爱上用swagger写文档。他不接可以自动生成文档，而且可以直接用来做接口测试。

首先安装 swagger

go get -u github.com/swaggo/swag/cmd/swag    go get -u github.com/swaggo/gin-swagger/swaggerFiles

1、入口文件引入swagger配置

package main    import (  "ginLearn.com/controller"  _ "ginLearn.com/docs"  "github.com/gin-gonic/gin"  "github.com/swaggo/gin-swagger"  "github.com/swaggo/gin-swagger/swaggerFiles")    // @title Gin swagger// @version 1.0// @description Gin swagger 示例项目    // @contact.name hanyun// @contact.url// @contact.email [email protected]    // @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host localhost:8080func main() {  router := gin.Default()  router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))  router.GET("/api/v1", controller.Index)  router.Run()}

值得注意的一点是，已定义记着定义`_ "ginLearn.com/docs"`,要不swagger无法正常的解析页面，因为我是采用gomodule的方式，我定义的`module ginLearn.com`，各位可以把“ginLearn.com”替换为自己定义的。

swagger服务注释解释说明

// @title Gin swagger  展示在web端的title上// @version 1.0 定义接口的版本// @description Gin swagger 示例项目 首页展示// @securityDefinitions.apikey ApiKeyAuth  API的认证方式// @in header 发送认证的方式// @name Authorization  后端获取认证值得方式    // @contact.name hanyun 联系人信命// @contact.url 联系人的个人首页地址// @contact.email [email protected] 联系人的邮箱    // @license.name Apache 2.0 文档采用的协议// @license.url http://www.apache.org/licenses/LICENSE-2.0.html 协议地址// @host localhost:8080 文档服务器的地址

2、在具体的方法上添加注释

package controller    import (  "ginLearn.com/response"  "github.com/gin-gonic/gin")    // @Tags 首页// @Id 1// @Summary 获得首页数据// @Description | 项目 | 价格 | 数量 |// @Description | :-------- | --------:| :--: |// @Description | iPhone | 6000 元 | 5 |// @Description | iPad | 3800 元 | 12 |// @Description | iMac | 10000 元 | 234 |// @Produce  json// @Security ApiKeyAuth// @Param id path int true "用户id"// @Param token header string true "用户token"// @Param name query string false "用户名"// @Param img formData file false "文件"// @Success 200 object  response.Result "成功"// @Failure 400 object  response.Result "失败"// @Router /api/v1/{id} [get]func Index(c *gin.Context) {  c.JSON(4000, response.Result{})}

swagger接口注释解释说明

@Summary 是对该接口的一个描述@Id 是一个全局标识符，所有的接口文档中 Id 不能标注@Tags 是对接口的标注，同一个 tag 为一组，这样方便我们整理接口@Security ApiKeyAuth 表示这是一个需要认证才可以调用的接口，对应// @securityDefinitions.apikey ApiKeyAuth@Version 表明该接口的版本@Accept 表示该该请求的请求类型@Param 表示参数 分别有以下参数 参数名词 参数类型 数据类型 是否必须 注释 属性(可选参数),参数之间用空格隔开。@Success 表示请求成功后返回，它有以下参数 请求返回状态码，参数类型，数据类型，注释@Failure 请求失败后返回，参数同上@Router 该函数定义了请求路由并且包含路由的请求方式。

有时候我们写文档需要markdown表格,swagger的注释也支持markdown语法

// @Description | 项目 | 价格 | 数量 |// @Description | :-------- | --------:| :--: |// @Description | iPhone | 6000 元 | 5 |// @Description | iPad | 3800 元 | 12 |// @Description | iMac | 10000 元 | 234 |