---

前言

在写前后端分离的后端项目的时候，我们常常写后端程序返回的大多都是restful API风格的JSON数据，

而Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言，配合gin框架使用就可以自动生成一份接口文档包括自动文档，代码生成和测试用例生成。

一、准备工作

go get -u github.com/swaggo/swag/cmd/swag下载这个包方便我们使用swag命令

二、添加注释

注释一般添加在两个地方，一个是main函数里，另外就是添加到api接口函数里

• main函数中

package main

// @title 这里写标题
// @version 这里写版本号
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path（eg：/api/v1）
func main() {
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

• 接口函数中

// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamArtList(请求参数结构体) false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponseArtList
// @Router /接口路由 [请求类型]
func GetArt(c *gin.Context) {
1
2
3
4
5
6
7
8
9
10
11

---

_ResponseArtList一般是在接口层再额外定义的用于swagger的结构体

// 文章列表接口数据信息
type _ResponseArticle struct {
	Code    int              `json:"code"`    //业务状态码
	Message string           `json:"message"` // 提示信息
	Data    *[]model.Article `json:"data"`    // 数据
}
1
2
3
4
5
6

如果还想添加其他注释可以看文档添加需要的注释：swagger注释

四、生成docs文件

注释添加完毕之后就应该在终端输入swag init这样项目中就会多一个docs文件

三、注册路由

然后再在router里面注册路由
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
注意要把docs文件导入router里

总结

这样项目启动就可以访问http://localhost:port/swagger/index.html看到接口文档了