衔接上文，继续开发。这一章主要是提供API接口文档。

其实不想写这一章的，但是…没办法。一点一点加吧。

GitHub项目地址：https://github.com/swaggo/gin-swagger

安装swag

go get -u github.com/swaggo/swag/cmd/swag

验证安装成功

[xiong@AMDServer ginBlog]$ swag -v
swag version v1.6.7

1 2	[xiong@AMDServer ginBlog]$ swag -v swag version v1.6.7

安装 gin-swagger

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

go get -u github.com/swaggo/files

增加注释

接下来我们以routers/api/v1/tag.go文件为例，按照Swagger的规范增加注释。

先只增加一个函数：

// AddTag 新增文章标签
// @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) {
	name := c.Query("name")
	state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()
	createdBy := c.Query("created_by")

	valid := validation.Validation{}
	valid.Required(name, "name").Message("名字不能为空")
	valid.MaxSize(name, 100, "name").Message("名称最长为100字符") //这个长度跟随数据库字段长度
	valid.Required(createdBy, "created_by").Message("创建人不能为空")
	valid.MaxSize(createdBy, 100, "created_by").Message("创建人最长为100字符")
	valid.Range(state, 0, 1, "state").Message("状态只允许0或者1")

	code := e.InvalidParams
	if !valid.HasErrors() {
		if !models.IsExistTagByName(name) {
			code = e.Success
			models.AddTag(name, state, createdBy)
		} else {
			code = e.ErrorTagExist
		}
	} else {
		for _, err := range valid.Errors {
			logging.Info(err.Key, err.Message)
		}
	}

	c.JSON(http.StatusOK, gin.H{
		"code": code,
		"msg":  e.GetMsg(code),
		"data": make(map[string]string),
	})
}

// AddTag 新增文章标签

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

name := c.Query("name")

state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()

createdBy := c.Query("created_by")

valid := validation.Validation{}

valid.Required(name, "name").Message("名字不能为空")

valid.MaxSize(name, 100, "name").Message("名称最长为100字符") //这个长度跟随数据库字段长度

valid.Required(createdBy, "created_by").Message("创建人不能为空")

valid.MaxSize(createdBy, 100, "created_by").Message("创建人最长为100字符")

valid.Range(state, 0, 1, "state").Message("状态只允许0或者1")

code := e.InvalidParams

if !valid.HasErrors() {

if !models.IsExistTagByName(name) {

code = e.Success

models.AddTag(name, state, createdBy)

} else {

code = e.ErrorTagExist

}

} else {

for _, err := range valid.Errors {

logging.Info(err.Key, err.Message)

}

c.JSON(http.StatusOK, gin.H{

"code": code,

"msg": e.GetMsg(code),

"data": make(map[string]string),

})

}

生成API文档

进入项目根目录，执行 swag init 命令：

[xiong@AMDServer ginBlog]$ swag init
2020/09/09 13:03:00 Generate swagger docs....
2020/09/09 13:03:00 Generate general API Info, search dir:./
2020/09/09 13:03:00 create docs.go at docs/docs.go
2020/09/09 13:03:00 create swagger.json at docs/swagger.json
2020/09/09 13:03:00 create swagger.yaml at docs/swagger.yaml

[xiong@AMDServer ginBlog]$ swag init

2020/09/09 13:03:00 Generate swagger docs....

2020/09/09 13:03:00 Generate general API Info, search dir:./

2020/09/09 13:03:00 create docs.go at docs/docs.go

2020/09/09 13:03:00 create swagger.json at docs/swagger.json

2020/09/09 13:03:00 create swagger.yaml at docs/swagger.yaml

查看目录树

[xiong@AMDServer ginBlog]$ tree
.
├── conf
│   └── app.ini
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
├── main
├── main.go
├── middleware
│   └── jwt
│       └── jwt.go
├── models
│   ├── article.go
│   ├── auth.go
│   ├── models.go
│   └── tag.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── logging
│   │   ├── file.go
│   │   └── log.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       ├── jwt.go
│       └── pagination.go
├── routers
│   ├── api
│   │   ├── auth.go
│   │   └── v1
│   │       ├── article.go
│   │       └── tag.go
│   └── router.go
└── runtime
    └── logs
        ├── log20200906.log
        └── log20200908.log

15 directories, 26 files

[xiong@AMDServer ginBlog]$ tree

├── conf

│ └── app.ini

├── docs

│ ├── docs.go

│ ├── swagger.json

│ └── swagger.yaml

├── go.mod

├── go.sum

├── main

├── main.go

├── middleware

│ └── jwt

│ └── jwt.go

├── models

│ ├── article.go

│ ├── auth.go

│ ├── models.go

│ └── tag.go

├── pkg

│ ├── e

│ │ ├── code.go

│ │ └── msg.go

│ ├── logging

│ │ ├── file.go

│ │ └── log.go

│ ├── setting

│ │ └── setting.go

│ └── util

│ ├── jwt.go

│ └── pagination.go

├── routers

│ ├── api

│ │ ├── auth.go

│ │ └── v1

│ │ ├── article.go

│ │ └── tag.go

│ └── router.go

└── runtime

└── logs

├── log20200906.log

└── log20200908.log

15 directories, 26 files

可以看到在项目根目录下生成 docs 文件夹。

添加路由

我们需要将 Swagger 的路由添加到 routers.go文件中。修改文件如下：

package routers

import (
	"ginBlog/middleware/jwt"
	"ginBlog/pkg/setting"
	"ginBlog/routers/api"
	v1 "ginBlog/routers/api/v1"

	_ "ginBlog/docs" //导入Swagger的docs包

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

//InitRouter 初始化路由
func InitRouter() *gin.Engine {
	r := gin.New()

	r.Use(gin.Logger())
	r.Use(gin.Recovery())

	gin.SetMode(setting.GetRunMode())

	//账户路由
	{
		r.Group("/api").GET("/auth", api.GetAuth)
	}

	//Swagger API文档路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	apiv1 := r.Group("/api/v1")
	apiv1.Use(jwt.JWT())
	{
		//标签路由
		apiv1.GET("/tags", v1.GetTags)
		apiv1.POST("/tags", v1.AddTag)
		apiv1.PUT("/tags/:id", v1.EditTag)
		apiv1.DELETE("/tags/:id", v1.DeleteTag)

		//文章路由
		apiv1.GET("/articles", v1.GetArticles)
		apiv1.GET("/articles/:id", v1.GetArticle)
		apiv1.POST("/articles", v1.AddArticle)
		apiv1.PUT("/articles/:id", v1.EditArticle)
		apiv1.DELETE("/articles/:id", v1.DeleteArticle)
	}

	return r
}

package routers

import (

"ginBlog/middleware/jwt"

"ginBlog/pkg/setting"

"ginBlog/routers/api"

v1 "ginBlog/routers/api/v1"

_ "ginBlog/docs" //导入Swagger的docs包

"github.com/gin-gonic/gin"

swaggerFiles "github.com/swaggo/files"

ginSwagger "github.com/swaggo/gin-swagger"

)

//InitRouter 初始化路由

func InitRouter() *gin.Engine {

r := gin.New()

r.Use(gin.Logger())

r.Use(gin.Recovery())

gin.SetMode(setting.GetRunMode())

//账户路由

{

r.Group("/api").GET("/auth", api.GetAuth)

}

//Swagger API文档路由

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

apiv1 := r.Group("/api/v1")

apiv1.Use(jwt.JWT())

{

//标签路由

apiv1.GET("/tags", v1.GetTags)

apiv1.POST("/tags", v1.AddTag)

apiv1.PUT("/tags/:id", v1.EditTag)

apiv1.DELETE("/tags/:id", v1.DeleteTag)

//文章路由

apiv1.GET("/articles", v1.GetArticles)

apiv1.GET("/articles/:id", v1.GetArticle)

apiv1.POST("/articles", v1.AddArticle)

apiv1.PUT("/articles/:id", v1.EditArticle)

apiv1.DELETE("/articles/:id", v1.DeleteArticle)

}

return r

}

添加了Swagger路由，导入了3个包。

注意必要的Doc包： _ “ginBlog/docs” //导入Swagger的docs包

验证API文档

最后我们访问 192.168.1.101:8000/swagger/index.html 查看API文档。

补齐注释

最后一步就是补齐注释，这里不做说明了。

【Go】gin Blog项目(七) Swagger API文档

Tagged on: Go Web