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
|
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() { r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler( swaggerFiles.Handler, ginSwagger.DefaultModelsExpandDepth(-1), ), ) 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"` }
func (t User) Login(c *gin.Context) {
}
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文档