Go Swagger 安装使用

Go Swagger 安装使用

# 下载
go get -u github.com/swaggo/swag/cmd/swag

安装
工作目录移动到GOPATH\pkg\mod\github.com\swaggo\[email protected]下执行
GOPATH指的是Golang的GOPATH所在目录，比如我的就在D:/GOPATH这里
如果不清楚自己GOPATH目录在哪里，而且正好用的是GoLand，可以到GoLand中找到文件 -> 设置 -> Go -> GoPath 查看自己的GOPATH路径

# 移动到GOPATH\pkg\mod\github.com\swaggo\[email protected] 注意版本号，如果不一样记得改下
cd D:\GOPATH\pkg\mod\github.com\swaggo\[email protected]
go install ./cmd/swag

按照swagger要求给接口代码添加声明式注释

具体参照声明式注释格式。

下面的例子中，只要是注释后面的描述用括号括起来的，那么括号前那一段就是示例，下面这些内容也都是上面的声明时注释格式中的内容

main函数注释

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService API服务条款

// @contact.name 联系人姓名
// @contact.url 联系url
// @contact.email 联系email

// @license.name Apache 2.0 (必需的。用于 API 的许可证名称。)
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html (用于API的许可证的URL。必须采用URL的格式。)

// @host 为 API 提供服务的主机（名称或 IP）。
// @BasePath 提供 API 的基本路径。
func main() {
	r := gin.New()
	//...
	r.Run()
}

API注释

// 函数名 函数描述
// @Summary 操作的简短摘要。
// @Description 操作行为的详细说明。
// @Tags 每个 API 操作的标签列表，以逗号分隔。
// @Accept application/json (API 可以使用的 MIME 类型列表。值必须如 Mime 类型中所述。)
// @Produce application/json (API 可以生成的 MIME 类型列表。值必须如 Mime 类型中所述。)
// @Param Authorization header string true "Bearer 用户令牌" (以空格分隔的参数。参数名称 参数类型 数据类型 是否必填 注释属性（可选）)
// @Param object query models.ParamPostList false "查询参数" (同上)
// @Security ApiKeyAuth (每个 API 操作的安全性。)
// @Success 200 {object} ResponseData (以空格分隔的成功响应。返回码 {参数类型} 数据类型 注释)
// @Faliure 1001 {object} ResponseData (以空格分隔的失败响应。返回码 {参数类型} 数据类型 注释)
// @Router /LoginHandler [post] (以空格分隔的失败响应。路径，[http方法])
func LoginHandler(c *gin.Context) {
	/**
		...
			**/
}

使用swag工具扫描代码自动生成API接口文档数据

# 如果是刚安装的swagger，记得把工作目录切换回项目目录
swag init

如果这一步发生了错误，而错误类似于未找到 swag 命令，那么问题就出现在没有将GOPATH添加到环境变量中，只用把 GOPATH目录/bin 文件夹添加到环境变量之后，重启GoLand，就能解决

执行完上述命令后，此时项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

引入gin-swagger渲染在线接口文档页面

在项目代码中注册路由的地方按如下方式引入gin-swagger相关的这三条内容：

import(
	_ "项目目录/docs"
	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/files"
)

注册swagger api相关路由

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

把项目程序运行起来，打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger文档了。

gin-swagger同时还提供了DisablingWrapHandler函数，方便我们通过设置某些环境变量来禁用Swagger。例如：

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

此时如果将环境变量NAME_OF_ENV_VARIABLE设置为任意值，则/swagger/*any将返回404响应，就像未指定路由时一样。