gin-swagger 的使用

gin-swagger 的使用

Swagger中文文档

准备工作

引入swaggo依赖:

1
2
3
4
5
6
7
## swagger 依赖/也可以通过先import,再运行go mod tidy下载gin-swagger
go get -u "github.com/swaggo/files"
go get -u "github.com/swaggo/gin-swagger"

## swagger 命令行工具
go get -u github.com/swaggo/swag/cmd/swag
go install github.com/swaggo/swag/cmd/swag@latest

项目地址:gin-swagger项目地址

进入正题

1、首先在main函数前添加描述:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//    @title            helloworld
// @version 1.0
// @description liuxing test helloworld
// @termsOfService http://swagger.io/terms/
// @contact.name lx
// @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 lx.helloworld.com
// @BasePath /base/path
func main() {

}

2、注册swagger路由信息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import (
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)

func main() {
//注册swagger路由
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(
swaggerFiles.Handler,
ginSwagger.DefaultModelsExpandDepth(-1), // 设置不显示model
//ginSwagger.URL("/swagger/doc.json"), // "/swagger/doc.json" 为默认项,可省略,该函数可用来指定doc.json地址
),
)
user := NewUser()
apiv1 := r.Group("/api/v1")
{
u := apiv1.Group("user")
{
u.POST("/login", user.Login)
u.POST("/logout", user.Logout)
}
}
r.Run(":8080")
}

3、 给函数方法添加备注:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
type StandardResponse struct {
Success bool `json:"success"`
Data interface{} `json:"data"`
Message string `json:"message"`
Code int `json:"code"`
}

// @Summary 禅道登录接口
// @Produce json
// @Param account query string false "用户名"
// @Param password query string false "密码"
// @Success 200 {object} StandardResponse "成功"
// @Failure 400 {object} StandardResponse "请求错误"
// @Failure 500 {object} StandardResponse "内部错误"
// @Router /api/v1/user/login [post]
func (t User) Login(c *gin.Context) {

}

// @Summary 禅道登出接口
// @Produce json
// @Param zentaosid query string true "session_id"
// @Success 200 {object} StandardResponse "成功"
// @Failure 400 {object} StandardResponse "请求错误"
// @Failure 500 {object} StandardResponse "内部错误"
// @Router /api/v1/user/logout [post]
func (t User) Logout(c *gin.Context) {

}

4、文档初始化

1
2
swag init    # 初始化文档
swag fmt # 格式化文档

swag init执行成功之后会在项目目录下出现 docs 子目录,子目录中会出现 docs.go,swagger.json,swagger.yaml 三个文件,随后在 main 文件中 import docs 模块

回自动在项目顶层生成以下结构

1
2
3
4
5
6
7
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── main.go
1
2
3
import (
_ "xxx/docs" // 启用swagger文档功能必须添加该条import,否则无法调用doc.json
)

5、编译运行

编译运行服务,访问本地 http://localhost:8080/swagger/index.html 即可访问swagger文档