前言
在写前后端分离的后端项目的时候，我们常常写后端程序返回的大多都是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() {
- 接口函数中
// @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) {
_ResponseArtList一般是在接口层再额外定义的用于swagger的结构体
// 文章列表接口数据信息
type _ResponseArticle struct {
Code int `json:"code"` //业务状态码
Message string `json:"message"` // 提示信息
Data *[]model.Article `json:"data"` // 数据
}
如果还想添加其他注释可以看文档添加需要的注释：swagger注释
四、生成docs文件
注释添加完毕之后就应该在终端输入swag init这样项目中就会多一个docs文件
三、注册路由
然后再在router里面注册路由r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
注意要把docs文件导入router里
总结
这样项目启动就可以访问http://localhost:port/swagger/index.html看到接口文档了
