官方:
https://github.com/swaggo/gin-swagger
开始使用
- 为API方法增加注释,加在controller(api)层, See Declarative Comments Format.
- 运行下面命令下载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
- 在你的go项目根目录运行swga(上文下载的exe)(比方说
~/root/go-project-name), Swag 会分析注释生成必要的文件(docsfolder anddocs/doc.go) at~/root/go-project-name/docs.
swag init
- 下载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 mainimport ("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
)
