go gin swagger安装与使用

Posted 2023-05-15 5656923

原文链接：https://blog.csdn.net/joychenwenyu/article/details/126935706

进入正题

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

准备工作

引入swaggo依赖：

## swagger 依赖
go get "github.com/swaggo/files"
go get "github.com/swaggo/gin-swagger"


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

 

进入正题

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

// @title ginchat
// @version 1.0
// @description chenweihao test gonchat
// @termsOfService http://swagger.io/terms/

// @contact.name cwh
// @contact.url http://www.swagger.io/support
// @contact.email [e-mail]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath
func main() 
   utils.InitConfig()
   utils.InitMysql()
   r := router.Router()
   r.Run() // 监听并在 0.0.0.0:8080 上启动服务


2、注册swagger路由信息：

_ "ginchat/docs" 这个记得引入 不然会报错

import (
   _ "ginchat/docs"
   "ginchat/service"
   "github.com/gin-gonic/gin"
   swaggerFiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
)

func Router() *gin.Engine 
   r := gin.Default()
   r.GET("/swagger/*any", func(c *gin.Context) 
      ginSwagger.DisablingWrapHandler(swaggerFiles.Handler, "SWAGGER")(c)
   )
   r.GET("/index/index", service.GetIndex)
   r.GET("/user/index", service.GetUserList)
   return r


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

// GetIndex
// @Tags 首页
// @Success 200 string welcome
// @Router /index/index [get]
func GetIndex(c *gin.Context) 
   c.JSON(200, gin.H
      "message": "welcome",
   )


4、文档初始化
swag init 

项目结构
```
./helloworld
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── src
├──cmd
├── main.go
```

 

5、编译运行

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

golang gin框架 使用swagger生成api文档

github地址：https://github.com/swaggo/gin-swagger

1、下载swag

$ go get -u github.com/swaggo/swag/cmd/swag

2、在main.go所在目录执行

$ swag init

生成docs/doc.go以及docs/swagger.json,docs/swagger.yaml

3、下载gin-swagger

$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

然后在路由文件引入

import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	"github.com/swaggo/gin-swagger"
	
	_ "github.com/swaggo/gin-swagger/example/basic/docs" // docs is generated by Swag CLI, you have to import it.
)

并增加swagger访问路由

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

 

3、一些注解，编写各API handler方法注释（注解格式传送门）

1）main.go主程序文件注释：

// @title Golang Esign API
// @version 1.0
// @description  Golang api of demo
// @termsOfService http://github.com

// @contact.name API Support
// @contact.url http://www.cnblogs.com
// @contact.email ×××@qq.com

//@host 127.0.0.1:8081
func main() 

2）handler方法注释：eg

//CreatScene createScene
// @Summary createScene
// @Description createScene
// @Accept multipart/form-data
// @Produce  json
// @Param app_key formData string true "AppKey"
// @Param nonce_str formData string true "NonceStr"
// @Param time_stamp formData string true "TimeStamp"
// @Success 200 object app.R
// @Failure 500 object app.R
// @Router /dictionaries/createScene [post]