煎鱼 Go Gin 系列八:为它加上Swagger-技术圈

涉及知识点

Swagger

本文目标

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

安装 swag

$ go get -u github.com/swaggo/swag/cmd/swag@v1.6.5

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

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

验证是否安装成功

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

$ swag -vswag version v1.6.5

安装 gin-swagger

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

注：若无科学上网，请务必配置 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 的注解规范和范例去编写

// @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 文件，新增内容如下：

package routers
import (    ...
 _ "github.com/EDDYCJY/go-gin-example/docs"
  ...)
// InitRouter initialize routing informationfunc InitRouter() *gin.Engine {  ...    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))   ...    apiv1 := r.Group("/api/v1")    apiv1.Use(jwt.JWT())   {      ...    }
   return r}

生成

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

[$ gin-blog]# swag init2018/03/13 23:32:10 Generate swagger docs....2018/03/13 23:32:10 Generate general API Info2018/03/13 23:32:10 create docs.go at  docs/docs.go

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

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

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

验证

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

image

参考

本系列示例代码

go-gin-example

推荐阅读

煎鱼 Go Gin 系列七：优雅的重启服务

喜欢本文的朋友，欢迎关注“Go语言中文网”：

Go语言中文网启用微信学习交流群，欢迎加微信：274768166，投稿亦欢迎