gin-swagger|青训营笔记

这是我参与「第五届青训营 」伴学笔记创作活动的第 6 天

今天的笔记内容是关于在gin框架开发过程中，对于Swagger技术的整合。

Swagger技术，在后端开发过程中属于很常见的一个接口文档整合，它可以帮助我们在与前端人员交互过程中更快的开发。

swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

在前后端分离的项目开发过程中，如果后端同学能够提供一份清晰明了的接口文档，那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而Swagger正是那种能帮我们解决接口文档问题的工具。

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

gin-swagger实战

想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：

第一步：添加注释

在程序入口main函数上以注释的方式写下项目相关介绍信息。

package main

// @title gin学习项目
// @version 1.0
// @description 这是一个关于帖子的发布编写内容
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 8081
// @BasePath /

func main() {
    .......
}

之后再controller层添加注释

// VoteDataChange 投票帖子接口
// @Summary 投票帖子接口
// @Description 可以投喜欢或者讨厌票
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query entity.ParamVoteData true "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponseVote
// @Router /vote/change [post]
func VoteDataChange(c *gin.Context) {
   // 参数校验
   p := new(entity.ParamVoteData)
   if err := c.ShouldBindJSON(p); err != nil {
      errs, ok := err.(validator.ValidationErrors) //类型断言
      if !ok {
         controller.ResponseError(c, controller.CodeInvalidParam)
         return
      }
      errData := controller.RemoveTopStruct(errs.Translate(controller.Trans)) // 翻译并去除错误中结构体名字
      controller.ResponseErrorWithMsg(c, controller.CodeInvalidParam, errData)
      return
   }

   //业务处理
   //获取用户id
   userID, err := controller.GetCurrentUser(c)
   if err != nil {
      controller.ResponseError(c, controller.CodeNeedLogin)
      return
   }
   if err := service.PostVote(userID, p); err != nil {
      zap.L().Error("service.PostVote(userID, p) failed", zap.Error(err))
      controller.ResponseError(c, controller.CodeServerBusy)
      return
   }
   controller.ResponseSuccess(c, controller.CodeSuccess)
   return
}

_ResponseVote一般我习惯于在自己定义一个新的结构体

type _ResponseVote struct {
   Code    ResCode `json:"code"`    //业务响应码
   Message string  `json:"message"` //提示信息
   Data    string  `json:"data"`    //数据
}

第二步：生成接口文档数据

首先进行导包操作

//swagger
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get github.com/swaggo/files

在项目根目录执行以下命令，使用swag工具生成接口文档数据。

swag init

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个docs文件夹。

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

第三步：引入gin-swagger渲染文档数据

然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容：

import (
	// liwenzhou.com ...

	_ "bluebell/docs"  // 千万不要忘了导入把你上一步生成的docs

	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"

	"github.com/gin-gonic/gin"
)

注册swagger api相关路由

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

把你的项目程序运行起来，打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文档了。

以上内容就是关于gin框架整合Swagger的全部操作了。