gin-swagger用法

https://github.com/swaggo/swag

安装 swag

1. 下载安装swag命令

//go版本1.16之前使用该命令
go get -u github.com/swaggo/swag/cmd/swag
​
//go版本1.16版本以及之后的版本使用该命令
go install github.com/swaggo/swag/cmd/swag@latest

安装 gin-swagger

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

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

编写API注释

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

gin-swagger 给出的范例：

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

我们可以参照 Swagger 的注解规范和范例去编写

// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {

// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {

生成

我们进入到项目根目录中，执行初始化命令

swag init 指定的文件就是包含了以下swagger通用注释的文件

//保证执行命令的位置与main.go在同一文件夹
swag init
​
//如果没有写main.go文件，可以使用 -g来指定 写有swagger通用api信息的文件路径
swag init -g http/api.go

执行swag init之后会生成一个文件夹 doc 查看doc/doc.go是否有问题，目前存在一个问题，是当swag 的版本是1.7.9时，执行swag init，会出现冲突可以参考：https://github.com/swaggo/swag/issues/1126

解决方法：安装预编译版本并下载另外一个包

go get github.com/swaggo/echo-swagger
go install github.com/swaggo/swag/cmd/[email protected]
​
//如果还是不行
go get github.com/alecthomas/template

导入相关的包以及加入swagger的路由：

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files
​
​
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/
​
// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]
​
// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
​
// @host      localhost:8080
// @BasePath  /api/v1
​
// @securityDefinitions.basic  BasicAuth
func main() {
    r := gin.Default()
​
    c := controller.NewController()
​
    v1 := r.Group("/api/v1")
    {
        accounts := v1.Group("/accounts")
        {
            accounts.GET(":id", c.ShowAccount)
            accounts.GET("", c.ListAccounts)
            accounts.POST("", c.AddAccount)
            accounts.DELETE(":id", c.DeleteAccount)
            accounts.PATCH(":id", c.UpdateAccount)
            accounts.POST(":id/images", c.UploadAccountImage)
        }
    //...
    }
    //加入swagger的路由，可以支持在页面访问
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

除了导入以上 ginSwagger “github.com/swaggo/gin-swagger”、swaggerFiles "github.com/swaggo/gin-swagger/swaggerFiles"两个包，还要将swag init的doc包导入进来，并可以对doc包里的内容进行修改

doc.go

var SwaggerInfo = &swag.Spec{
  Version:          "1.0",
  Host:             "localhost:9090",
  BasePath:         "",
  Schemes:          []string{},
  Title:            "gin-swagger",
  Description:      "gin-swagger 示例项目",
  InfoInstanceName: "swagger",
  SwaggerTemplate:  docTemplate_swagger,
}
​
func init() {
  swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}

启动

执行 swag init 刷新 doc文件

启动服务，访问页面 http://localhost:9090/swagger/index.html,查看相关注释是否生效

说明

对于注释位置，其实对于函数位置其实是无所谓的，你注释写在什么方法上都行，因为在生成swagger文件的时候，是根据你指定的包去扫描的，去扫描这个包里面的go文件，上面的func是否有相关注释，有注释，就能当成一个api，所以并不仅仅限制于 func(ctx *gin.context) 这样的函数，写在handle函数上面是为了方便于handle一一对应，对于程序员来说方便寻找，以及方便修改接口的同时修改swagger

swagger的核心就是，获取项目的swagger api信息，将swagger信息通过项目路由出去

swagegr与其他web项目的结合也就是为了方便路由，对于获取项目的swagger api 可以使用注释以及 swag init命令的形式获取swag init命令的详细使用如下：

swag init -h
NAME:
   swag init - Create docs.go
​
USAGE:
   swag init [command options] [arguments...]
​
OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")