「连载八」为它加上Swagger

涉及知识点

• Swagger

本文目标

一个好的 API's，必然离不开一个好的 API 文档，如果要开发纯手写 API 文档，不存在的（很难持续维护），因此我们要自动生成接口文档。

安装 swag

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

PS F:\Projects\Go\bin> go install github.com/swaggo/swag/cmd/swag@latest

若$GOROOT/bin 没有加入 $PATH 中，你需要执行将其可执行文件移动到 $GOBIN 下

mv $GOPATH/bin/swag /usr/local/go/bin

验证是否安装成功

检查 $GOBIN 下是否有 swag 文件，如下：

PS F:\Projects\Go\bin> swag -v

安装 gin-swagger

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

PS F:\Projects\NoobWu\go-samples\go-gin-demo> go get -u github.com/swaggo/gin-swagger
go: downloading github.com/swaggo/swag v1.5.1
go: downloading golang.org/x/net v0.0.0-20210226172049-e18ecbb05110
go: downloading github.com/go-openapi/jsonreference v0.19.0
go: downloading github.com/go-openapi/spec v0.19.0
go: downloading github.com/pkg/errors v0.9.1
go: downloading golang.org/x/tools v0.0.0-20190611222205-d73e1c7e250b
go: downloading github.com/PuerkitoBio/purell v1.1.0
go: downloading github.com/go-openapi/jsonpointer v0.17.0
go: downloading github.com/go-openapi/swag v0.17.0
go: downloading github.com/mailru/easyjson v0.0.0-20180823135443-60711f1a8329
go get: added github.com/KyleBanks/depth v1.2.1
go get: added github.com/PuerkitoBio/purell v1.1.1
go get: added github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578
go get: added github.com/go-openapi/jsonpointer v0.19.5
go get: added github.com/go-openapi/jsonreference v0.19.6
go get: added github.com/go-openapi/spec v0.20.3
go get: added github.com/go-openapi/swag v0.19.15
go get: added github.com/josharian/intern v1.0.0
go get: added github.com/mailru/easyjson v0.7.7
go get: added github.com/pkg/errors v0.9.1
go get: added github.com/swaggo/gin-swagger v1.3.2
go get: added github.com/swaggo/swag v1.7.3
go get: upgraded golang.org/x/net v0.0.0-20210226172049-e18ecbb05110 => v0.0.0-20210928044308-7d9f5e0b762b
go get: upgraded golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e => v0.1.7
PS F:\Projects\NoobWu\go-samples\go-gin-demo> go get -u github.com/swaggo/files
go: downloading github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2
go get: upgraded github.com/swaggo/files v0.0.0-20190704085106-630677cd5c14 => v0.0.0-20210815190702-a29dd2bc99b2
PS F:\Projects\NoobWu\go-samples\go-gin-demo> go get -u github.com/alecthomas/template
go get: added github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
PS F:\Projects\NoobWu\go-samples\go-gin-demo>

注：若无科学上网，请务必配置 Go modules proxy。

初始化

编写 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 的注解规范和范例去编写
F:\Projects\NoobWu\go-samples\go-gin-demo\routers\api\v1\tag.go

// @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) {

参考的注解请参见 go-gin-example。以确保获取最新的 swag 语法

路由

在完成了注解的编写后，我们需要针对 swagger 新增初始化动作和对应的路由规则，才可以使用。打开 routers/router.go 文件，新增内容如下：
F:\Projects\NoobWu\go-samples\go-gin-demo\routers\router.go

package routers
import (
    "github.com/gin-gonic/gin"
    "github.com/noobwu/go-gin-demo/routers/api/v1"
    _ "github.com/noobwu/go-gin-demo/docs"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)
func InitRouter() *gin.Engine {
    r := gin.New()
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    apiv1 := r.Group("/api/v1")
    {
        //获取标签列表
        apiv1.GET("/tags", v1.GetTags)
        //新建标签
        apiv1.POST("/tags", v1.AddTag)
        //更新指定标签
        apiv1.PUT("/tags/:id", v1.EditTag)
        //删除指定标签
        apiv1.DELETE("/tags/:id", v1.DeleteTag)
    }
    return r
}

生成

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

PS F:\Projects\NoobWu\go-samples\go-gin-demo> swag init

完毕后会在项目根目录下生成 docs

docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

我们可以检查 docs.go 文件中的 doc 变量，详细记载中我们文件中所编写的注解和说明

验证

大功告成，访问一下 http://127.0.0.1:8000/swagger/index.html， 查看 API 文档生成是否正确

参考

本系列示例代码

• go-gin-example

  https://www.cnblogs.com/twojin/p/11733694.html

原文链接

https://eddycjy.com/posts/go/gin/2018-03-18-swagger/