Gin-swaggo为gin框架提供Swagger 文档

官方:

https://github.com/swaggo/gin-swagger

开始使用

1. 为API方法增加注释,加在controller(api)层, See Declarative Comments Format.
2. 运行下面命令下载swgo:

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

Go 1.17后的版本, 使用 go get 安装可执行文件已被废弃. 用go install代替:

go install github.com/swaggo/swag/cmd/swag@latest

1. 在你的go项目根目录运行swga(上文下载的exe)(比方说 ~/root/go-project-name), Swag 会分析注释生成必要的文件(docs folder and docs/doc.go) at ~/root/go-project-name/docs.

swag init

1. 下载gin-swagger by using:

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

Import following in your code:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

规范示例：
现在假设您已经实现了一个简单的 api，如下所示：

// get 函数，通过 json 返回 hello world 字符串
func Helloworld(g *gin.Context) {
g.JSON(http.StatusOK,"helloworld")
}
那么如何在上面的api上使用gin-swagger呢？只需遵循以下指南即可。

那么如何在上面的api上使用gin-swagger呢？只需遵循以下指南即可。

1.使用 gin-swagger 规则为 api 和 main 函数添加注释，如下所示：

// @BasePath /api/v1
 
// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

2.使用 swag init 命令生成一个文档，生成的文档将存储在 docs/ 中。

3.像这样导入文档：我假设您的项目名为 github.com/go-project-name/docs。

import (
   docs "github.com/go-project-name/docs"
)

4.构建您的应用程序，然后访问 http://localhost:8080/swagger/index.html ，您将看到您的 Swagger UI。

5.完整的代码和文件夹亲属在这里：

package main
 
import (
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   "net/http"
)
// @BasePath /api/v1
 
// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
   g.JSON(http.StatusOK,"helloworld")
}
 
func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1"
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld",Helloworld)
      }
   }
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")
 
}

测试用项目树, swag init 在 .目录运行

.
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go