基于gin的golang web开发：集成swagger

在前后端分离的项目维护一份完整且及时更新的api文档会极大的提高我们的工作效率，传统项目中接口文档都是由后端开发手写的，这种文档很难保证及时性，久而久之便失去了参考意义。swagger给我们提供了一种新的维护文档的方式，在gin中只需要编写一些注释即可生成一份可交互的接口文档。

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
复制代码

github.com/swaggo/swag/cmd/swaggithub.com/swaggo/gin-swaggergithub.com/swaggo/files

与gin集成

我们需要在代码中引入必要的包，并且在main方法上增加两个必填的通用API注释title和version，这两个注释分别表示应用程序的名称和应用程序API的版本，这些内容会显示在swagger ui中。代码如下：

package main

import (
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "proj/docs"
)

// @title 用户中心API
// @version 1.0
func main() {
	engine := gin.Default()

	url := ginSwagger.URL("/swagger/doc.json")
	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

	_ = engine.Run(":8081")
}
复制代码

doc.json

main.goswag init_ "proj/docs"

编写接口注释信息

type SysRole struct {
	Id          int64       `json:"id"`
	Name        null.String `json:"name" swaggertype:"string"` // 角色名
	Description null.String `json:"description" swaggertype:"string"`
	Available   null.Int    `json:"available" swaggertype:"integer"`
	CreateTime  null.Time   `json:"create_time" db:"create_time" swaggertype:"string"` // 添加时间
	UpdateTime  null.Time   `json:"update_time" db:"update_time" swaggertype:"string"` // 更新时间
}

// 角色列表
// @Summary 角色列表
// @Description 角色列表
// @Tags 角色
// @Success 200 {array} SysRole
// @Router /roles [get]
func RoleList(c *gin.Context) {
	list := sysRole.GetAllRole()

	c.JSON(http.StatusOK, list)
}
复制代码

我们分别在model和handler方法上增加一些必要的信息。

swag init

ParseComment error in file xxxxxxx.go :cannot find package path of type: null.String
复制代码

swag init --parseDependencyswaggertypeswaggertypeswaggertype:"integer"

@Tags 角色