Go-Swagger

安装依赖

# swagger
go get -u github.com/swaggo/swag/cmd/swag
go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/files
go get -u github.com/swaggo/gin-swagger
1
2
3
4
5

文档

文档地址

使用方式

1. main函数添加注释

package main

import (
	"ToDoList/initialize"
)

// @title To-Do-List Swagger API接口文档
// @version v1.0
// @description 待办事项
// @termsOfService http://swagger.io/terms/
// @contact.name cwy
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @BasePath /api/
func main() {}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

2. 注册中间件

func (receiver ginEngine) InitMiddleware() {
	// cors跨域中间件
	global.GVA_SERVER.Use(middleware.CorsByRules())
	// swagger中间件
	docs.SwaggerInfo.BasePath = global.GVA_CONFIG.App.RouterPrefix
	global.GVA_SERVER.GET(global.GVA_CONFIG.App.RouterPrefix+"/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

global.GVA_SERVER = GinEngine.InitEngine()
if global.GVA_SERVER != nil {
	// 注册中间件
	GinEngine.InitMiddleware()
	// 注册路由
	GinEngine.InitRouter()
	// 运行服务
	global.GVA_SERVER.Run(fmt.Sprintf(":%s", global.GVA_CONFIG.App.Port))
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

3. 控制器添加注释并定义返回的数据类型

package response
type LoginRes struct {
	User      model.User `json:"user"`
	Token     string     `json:"token"`
	ExpiresAt int64      `json:"expiresAt"`
}
// Login
// @Tags     User
// @Summary  用户登录
// @Produce   application/json
// @Param    data  body      request.Login                                             true  "用户名, 密码, 验证码"
// Success  200   {object}  response.LoginRes{data=response.LoginRes,msg=string}  "返回包括用户信息,token,过期时间"
// @Router   /user/login [post]
func (receiver *userApi) Login(c *gin.Context) {}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

4. 初始化swagger执行以下命令,并生成如图目录结构

swag init -g main.go -o ./docs
1

5. 打开swagger地址http://localhost:8329/[这里写main函数中的BasePath]/swagger/index.html