【Web】go后端自动生成文档神器 gin - swagger gin 中间件自动生成 RESTful API 文档。

官方的解释很清晰,我这里翻译一下
[官方github](swaggo/gin-swagger:gin 中间件,使用 Swagger 2.0 自动生成 RESTful API 文档。 (github.com))

gin-swagger 作用

gin 中间件,使用 Swagger 2.0 自动生成 RESTful API 文档,前后端交互文档,防止扯皮

使用

  1. 使用以下方法下载 Swag for Go:
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项目根路径(例如)运行Swag,Swag会解析注释并生成所需的文件(文件夹和) 在。~/root/go-project-name``docs``docs/doc.go``~/root/go-project-name/docs
swag init
  1. 使用以下方法下载gin-swagger:
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

在代码中导入以下内容:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
  1. 在api上按照规定的注释规则注释,完整的代码和文件夹关系如下:
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
  1. 构建您的应用程序,然后转到 http://localhost:8080/swagger/index.html,您会看到您的 Swagger UI。

注释规则

  • title 必填。应用程序的标题。@title swagger API
  • version 必填。提供应用程序 API 的版本。@version 1.0|
  • description 应用程序的简短说明。@description 这是一个示例服务器单元服务器。
  • tag.name 标记的名称。@tag 这是标签的名称
  • tag.description 标签的说明 @tag.描述 酷炫描述|
  • tag.docs.url 标签的外部文档的网址 @tag.docs.url https://example.com
  • 等等

[强烈看官方的注解规则](swag/README.md at master · swaggo/swag (github.com))

你可能感兴趣的:(Web,前端,golang,gin,后端,swagger)