安装swag
go get -u github.com/swaggo/swag/cmd/swag
这里发现为什么安装了之后为什么找不到swag呢
然后去GOPATH下找bin目录里面没有swag.exe的可执行文件 在官方文档中说在GO 1.17之后不在支持go get的时候下载可执行文件可以通过go install下载
go install github.com/swaggo/swag/cmd/swag@latest
执行完成之后就可以看到有了，同时可以在bin目录下找到可执行文件
注意：如果这里还是找不到，但是bin目录中有，可以通过go env查看GOBIN是否有值，如果没有说明环境变量配置有问题
swag init
如果以上步骤都没有问题的话，那么执行完成会生产一个docs的文件夹
安装gin-Swagger
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
创建一个路由
// 初始化Swagger
func InitSwagRouter(r *gin.Engine) {
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
启动项目
启动项目访问ip:prot/swagger/index.html
这个时候会发现突然报错了，控制台也是
主要原因是没有找到doc.json
大家应该记得我们上面通过swag init生成了一个docs的包
但是我们还没有使用过，在官方文档中也提到了，我们需要引入
然后我们重新启动一下我们的程序就发现成功了
配置
官方参数文档： swaggo.github.io/swaggo.io/d…
| annotation | description | example |
|---|---|---|
| title | **必需的。**应用程序的标题。 | // @title Swagger Example API |
| version | **必需的。**提供应用程序API的版本。 | // @version 1.0 |
| description | 应用程序的简短描述。 | // @description This is a sample server celler server. |
| termsOfService | API的服务条款。 | // @termsOfService swagger.io/terms/ |
| contact.name | 公开的API的联系信息。 | // @contact.name API Support |
| contact.url | T指向联系信息的URL。必须采用网址格式。 | // @contact.url www.swagger.io/support |
| contact.email | 联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。 | // @contact.email support@swagger.io |
| license.name | **必需的。**用于API的许可证名称。 | // @license.name Apache 2.0 |
| license.url | 用于该API的许可证的URL。必须采用网址格式。 | // @license.url www.apache.org/licenses/LI… |
| host | 提供API的主机（名称或IP）。 | // @host localhost:8080 |
| BasePath | 提供API的基本路径。 | // @BasePath /api/v1 |
api 配置
| annotation | description |
|---|---|
| description | 操作行为的详细说明。 |
| id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 |
| tags | 每个API操作的标签列表，以逗号分隔。 |
| summary | 该操作的简短摘要。 |
| accept | API可以使用的MIME类型的列表。值必须与“ Mime类型”下所述相同。 |
| produce | API可以产生的MIME类型的列表。值必须与“ Mime类型”下所述相同。 |
| param | 用空格分隔的参数。param name，param type，data type，is mandatory?，comment attribute(optional) |
| security | 每个API操作的安全性。 |
| success | 成功响应之间用空格隔开。return code，{param type}，data type，comment |
| failure | 由空格分隔的故障响应。return code，{param type}，data type，comment |
| router | 由空格分隔的故障响应。path，[httpMethod] |
配置示例
// @title go-project-first
// @version 1.0.0
// @description 第一个go项目
func main() {
defer cmd.Clear()
cmd.Start()
}
// api.go
// @tags 用户
// @summary 用户登入接口
// @description 用户登入接口
// @param name formData string true "用户名"
// @param password formData string true "密码"
// @success 200 {string} string "成功"
// @router /api/v1/public/login [post]
func (u ULogin) Login(context *gin.Context) {
context.AbortWithStatusJSON(http.StatusOK, gin.H{
"msg": "登入成功",
"success": true,
})
}
