Go Swagger 安装使用

下载安装

# 执行
go install github.com/swaggo/swag/cmd/swag@latest

然后直接执行

swag

成功的话会显示如下内容

# 执行结果
NAME:
   swag.exe - Automatically generate RESTful API documentation with Swagger 2.0 for Go.

USAGE:
   swag.exe [global options] command [command options] [arguments...]

VERSION:
   v1.8.10

COMMANDS:
   init, i  Create docs.go
   fmt, f   format swag comments
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

如果出现以下内容，请将GOPATH/bin添加至环境变量PATH中(GOPATH指的是Golang的GOPATH所在目录)

swag : 无法将“swag”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

'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响应，就像未指定路由时一样。