这篇文章我们讲解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 1355081829@qq.com

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
func 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 1355081829@qq.com 联系人的邮箱

// @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 |

需要源码的小伙伴可以去百度云下载

链接：pan.baidu.com/s/11_9zBngn… 提取码：kfph