Gin学习笔记
1.gin框架图解概览
2.gin框架介绍
Gin 是一个用 Go (Golang) 编写的 web 框架。 它是一个类似于 martini 但拥有更好性能的 API 框架，由于 httprouter，速度提高了近 40 倍。是一款不错的web框架。
特性如下所示:
快速
--基于 Radix 树的路由，小内存占用。没有反射。可预测的 API 性能。
支持中间件
--传入的 HTTP 请求可以由一系列中间件和最终操作来处理。 例如：Logger，Authorization，GZIP，最终操作DB。
Crash 处理
--Gin 可以 catch 一个发生在 HTTP 请求中的 panic 并 recover 它。这样，你的服务器将始终可用。
JSON 验证
--Gin 可以解析并验证请求的 JSON，例如检查所需值的存在。
路由组
--更好地组织路由。是否需要授权，不同的 API 版本…… 此外，这些组可以无限制地嵌套而不会降低性能。
错误管理
--Gin 提供了一种方便的方法来收集 HTTP 请求期间发生的所有错误。最终，中间件可以将它们写入日志文件，数据库并通过网络发送。
内置渲染
--Gin 为 JSON，XML 和 HTML 渲染提供了易于使用的 API。
可扩展性
--中间件的扩展。
3.gin代码框架功能介绍
3.1 创建一个http服务。
如下示例为一个简便的http服务，以及响应信息
package main
import (
"github.com/gin-gonic/gin"
"net/http"
)
func main() {
r := gin.Default()
r.POST("/post", func(c *gin.Context) {
c.String(http.StatusOK, "Receive a post request !!!")
})
r.Run()
}
响应:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 16 Oct 2020 08:41:34 GMT
Content-Length: 28
Connection: close
"Receive a post request !!!"3.2.gin路由介绍：
在创建http服务时,访问都是基于路由进行请求消息传达,针对路由的使用分为路由,以及路由组使用。
3.2.1,单个路由使用实例。
如下代码所示:创建了POST请求的路由访问，通过调用注册的处理方法,处理相关的请求,除了post路由还有如下相关的路由请求,这里不做演示,根据具体代码可自行编写demo测试。
package main
import (
"github.com/gin-gonic/gin"
"net/http"
)
func main() {
r := gin.Default()
r.POST("/post", func(c *gin.Context) {
c.JSON(http.StatusOK, "Receive a post request !!!")
})
r.Run()
}3.2.2.路由组的使用
路由组,始终是在一个固定的路由路径下可以一批对应的路由信息,从而通过不同的路由来处理不同的请求访问。
如下代码所示:路由组，在gin中提供了Group方法，方法的定义:func (group *RouterGroup) Group(relativePath string, handlers ...HandlerFunc) *RouterGroup {}，参数分别为路由组名称，回调方法列表,在接收到对应路由请求,回调用对应的方法列表预先进行对应请求的处理,等价后面的gin中提供的中间件功能,后续会介绍该功能的使用方法。示例如下：
package main
import (
"fmt"
"github.com/gin-gonic/gin"
"net/http"
)
func OutFun() gin.HandlerFunc {
return func(c *gin.Context) {
fmt.Println("Request client ip is ", c.ClientIP())
c.Next()
}
}
func TotFun() gin.HandlerFunc {
return func(c *gin.Context) {
fmt.Println("Request url is ", c.Request.URL)
c.Next()
}
}
func main() {
r := gin.Default()
rh := r.Group("/user", OutFun(), TotFun())
{
rh.POST("/post", func(c *gin.Context) {
c.JSON(http.StatusOK, "This is /user/post request !")
})
rh.GET("/get", func(c *gin.Context) {
c.JSON(http.StatusOK, "This is /user/get request !")
})
}
r.Run()
}如上代码所示,在创建group路由组,自定义中间件方法在访问具体的路由前先进行相关处理，后在进行具体的请求处理，具体处理可行自行测试。
如下是gin提供路由方法,具体使用如同2.2.1.代码示例即可。
3.2.3,gin提供的其他路由方法如下。
r.GET("/someGet",getting)
r.GET("/user/:name/*action",getParams) //此种方法,表示/usr路由下后可以跟其他任意匹配的路由信息。
r.POST("/somePost",posting)
r.PUT("/somePut",putting)
r.DELETE("/someDelete",deleting)∫
r.PATCH("/somePatch",patching)
r.HEAD("someHead",heading)
r.OPTIONS("/someOptions",options)4,中间件的使用
4.1.在gin中的提供了中间件功能功能的使用,方便扩展代码扩展，使构建的服务更加完善。
gin中提供的New方法创建一个路由句柄,通过New方法创建的路由是不带中间件的。
如下代码:
package main
import (
"github.com/gin-gonic/gin"
"io"
"os"
)
//该方法模拟产生异常,用于服务中间件来进行捕获,并且开启一个文件,将日志写入文本,可查看异常的日志写入信息
func getFun(c *gin.Context) {
name := c.DefaultQuery("name","defaultName")
panic("test_panic")
c.String(200,"%v",name)
}
func main() {
/**
中间件的使用是实现服务运行过程所需要的一些特性方法
*/
//制定路由日志写入只对应的文本中
file, _:= os.Create("./gin.log")
//gin框架也可以指定写入的模块
gin.DefaultWriter = io.MultiWriter(file) //指定什么信息写入文本
gin.DefaultErrorWriter = io.MultiWriter(file) //固定错误也写入文本
r := gin.New() //创建一个无中间件的路由
r.Use(gin.Logger()) //使用日志中间件
r.Use(gin.Recovery()) //用于捕获程序的异常,防止程序出现挂掉的情况,将异常的信息会利用之前的插件写入到对应的文本中.
r.GET("/get",getFun)
r.Run()
}4.2自定义中间件
因系统中提供的中间件可能满足不了服务的所需,所以需要实际使用中需要我们自定义相关的中间件,以满足服务所需的特性处理。
中间件自定义是一个闭包函数或者最定义规则类型的方法即可,使用Use方法将中间件注册只路由管理中,中间件定义方式如下:
package main
import "github.com/gin-gonic/gin"
//自定义中间见使用
//检查请求的ip是否在列表中,请求过来调用中间件函数进行处理
//自定义中间件的闭包格式,返回的是一个HandlerFunc类型的方法。
//func OutFun() gin.HandlerFunc {
// return Infunc(c *gin.Context) {
// //TODO
// }
//}
func IpAuthos() gin.HandlerFunc { //自定义中间件都是返回该函数指针
return func(c *gin.Context) {
ipList := []string{
"127.0.0.1",
}
flag := false
clientip := c.ClientIP()
for _, host := range ipList {
if clientip == host {
flag = true
break
}
}
if !flag {
c.String(500, "%s is not ipList", clientip)
c.Abort() //中断请求,中间件执行失败,终断
}
c.Next() //执行下一个中间件方法
}
}
func getFun(c *gin.Context) {
c.String(200, "success !!!")
}
func main() {
r := gin.Default()
r.Use(IpAuthos()) //使用自定义中间件
r.GET("/get", getFun)
r.Run()
}4.4.在请求处理方法中使用协程
中间件或者处理方法中启动新协程不能使用原始的上下文，必须使用的是只读副本，具体示例如下:
package main
import (
"fmt"
"github.com/gin-gonic/gin"
"time"
)
func syncGet(cgp *gin.Context) {
time.Sleep(5 * time.Second)
cgp.String(200,"syncGet - %v",cgp.Request.URL.Path)
}
func main() {
r := gin.Default()
r.GET("/sget", func(c *gin.Context) {
time.Sleep(5 * time.Second)
fmt.Println("sycget - ",c.Request.URL.Path)
c.String(200,"sget - %v",c.Request.URL.Path)
})
r.GET("/sycget", func(c *gin.Context) {
//需要将主协程的上下文拷贝一份,在子协程中使用处理
cgp := c.Copy()
//服务函数重启一个协程来来处理,实现请求与返回异步处理
//界面收到处理结果,但实际后台还在处理,直到结果处理完成即可
go func() {
time.Sleep(5 * time.Second)
fmt.Println("sycget - ",cgp.Request.URL.Path)
//cgp.String(200,"sycget - %v",cgp.Request.URL.Path)
//cgp.JSON(200,gin.H{"message":cgp.Request.URL.Path})
}()
})
r.Run()
}4.5,解析请求中的json并绑定至结构体。
通过接受的请求，将请求的json信息绑定只结构体中，以便后续的业务处理，如下示例:
package main
import (
"fmt"
"github.com/gin-gonic/gin"
"net/http"
)
type myJson struct {
User string `json:"user"`
Passwd string `json:"passwd"`
}
//json
func getJson(c *gin.Context) {
req := myJson{}
//解析json绑定只结构
if err := c.ShouldBindJSON(&req);err == nil {
fmt.Println(req.User + req.Passwd)
if req.User == "lx" && req.Passwd == "llll" {
c.JSON(http.StatusOK,gin.H{"status":"you are logged in 2"})
} else {
c.JSON(http.StatusUnauthorized,gin.H{"status":"unauthorized 2"})
}
} else {
c.JSON(http.StatusBadRequest,gin.H{"error":err.Error()})
}
}
func main() {
r := gin.Default()
//json
r.POST("/loginJSON",getJson)
r.Run()
}4.6.如何优雅的停止服务。
通常启动http服务,直接通过Run方法启动服务，如下示例不使用Run启动服务,并且模拟服务异常，优雅的停止服务
package main
import (
"context"
"fmt"
"github.com/gin-gonic/gin"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
r := gin.Default()
r.GET("/test",func(c *gin.Context){
time.Sleep(10 * time.Second)
c.String(200,"hello self server !!!")
})
//不再使用run启动服务,自定义服务启动
svr := &http.Server{
Addr: ":8089",
Handler: r,
}
//利用一个协程启动服务
go func(){
if err := svr.ListenAndServe();err != nil && err != http.ErrServerClosed {
log.Fatalf("listen %s is",err)
}
}()
quit := make(chan os.Signal)
signal.Notify(quit,syscall.SIGINT,syscall.SIGTERM) //捕获两个信号
<-quit //利用通道让程序阻塞
log.Fatalf("shutdown server ...")
//context.Background() //返回一个空根节点,用于处理后续生成的叶子结点而存在,无过期时间限制
//创建一个超时上下文
//context.WithTimeout() 返回一个ctx上下文跟一个控制取消函数
ctx, Cancle := context.WithTimeout(context.Background(),10 * time.Second)
defer Cancle()
if err := svr.Shutdown(ctx); err != nil {
log.Fatalf("server shudown %s",err.Error())
}
fmt.Println("server exiting")
}另外通常使用的Run方法实质上内部调用也是httpserver服务，Run方法内部实现过程，示例代码：
func (engine *Engine) Run(addr ...string) (err error) {
defer func() { debugPrintError(err) }()
address := resolveAddress(addr)
debugPrint("Listening and serving HTTP on %s\n", address)
err = http.ListenAndServe(address, engine)
return
}
func ListenAndServe(addr string, handler Handler) error {
server := &Server{Addr: addr, Handler: handler}
return server.ListenAndServe()
}4.7,解析json只结构体的参数验证器使用：
package main
import (
"fmt"
"github.com/gin-gonic/gin"
)
//使用标签验证字段绑定
type Person struct {
Age int `form:"age" binding:"required,gt=10"` //直接使用标签验证相关字段的可行性
Name string `form:"name" binding:"required"`
Address string `form:"address" binding:"required"`
}
func get(c *gin.Context) {
pe := Person{}
if err := c.ShouldBind(&pe);err != nil {
fmt.Println(err.Error())
c.String(500,"%v",err)
} else {
c.String(200,"%v",pe)
}
}
func main() {
r := gin.Default()
r.GET("/get",get)
r.Run()
}
如上示例代码,发放请求的参数不符合规则,会报错，提示参数验证不正确。4.8,参数的获取Param(),Query(),PostForm()
如下代码示例子各种参数的获取方式:
package main
import (
"fmt"
"github.com/gin-gonic/gin"
"net/http"
)
//Param
func getParams(c *gin.Context) {
name := c.Param("name") //路径name
action := c.Param("action") //操作
message := name + " is " + action
fmt.Println(name, action)
c.String(http.StatusOK, message)
}
//Query
一般匹配这种形式的url /welcome?firstname=Jane&lastname=Doe
func getWelcome(c *gin.Context) {
firstname := c.DefaultQuery("firstname", "Guest") //如果没有值，还可以给一个默认值
lastname := c.Query("lastname")
c.String(http.StatusOK, "Hello %s %s ", firstname, lastname)
}
//PostForm
//curl -H "Content-Type: application/x-www-form-urlencoded" -X POST "http://127.0.0.1:8080/form_post" -d 'message=asdfg&nick=clear'
//使用如上方法传递对应参数即可获取url数据表单
func getForm(c *gin.Context) {
//使用如下方法获取url参数,header一定要为x-www-form-urlencoded
message := c.PostForm("message")
nick := c.DefaultPostForm("nick","guest")
fmt.Println(message + nick)
c.JSON(200,gin.H{"status":"posted","message":message,"nick":nick})
}
func main() {
//query param
//一般匹配这种形式的url /welcome?firstname=Jane&lastname=Doe
r := gin.Default()
r.GET("/welcome", getWelcome)
r.GET("/getParam",getParams)
r.GET("/getForm",getForm)
r.Run()
}4.9.匹配不定参数的路由
匹配格式：/路由/:参数名 or *参数名
package main
import (
"github.com/gin-gonic/gin"
"net/http"
)
func main() {
router := gin.Default()
//路由后面匹配相关的参数
// 此 handler 将匹配 /user/john 但不会匹配 /user/ 或者 /user,会返回404错误
router.GET("/user/:name", func(c *gin.Context) {
name := c.Param("name")
c.String(http.StatusOK, "Hello %s", name)
})
// 此 handler 将匹配 /user/john/ 和 /user/john/send
// 如果没有其他路由匹配 /user/john，它将重定向到 /user/john/
router.GET("/user/:name/*action", func(c *gin.Context) {
name := c.Param("name")
action := c.Param("action")
message := name + " is " + action
c.String(http.StatusOK, message)
})
router.Run()
}4.10,读取数据并解析
通过接收路由请求,通过另外一方调用请求读取数据,解析并返回对应的数据信息。
package main
import (
"github.com/gin-gonic/gin"
"net/http"
)
func main() {
router := gin.Default()
router.GET("/someDataFromReader", func(c *gin.Context) {
response, err := http.Get("https://www.tencent.com/zh-cn/about.html#about-con-1")
if err != nil || response.StatusCode != http.StatusOK {
c.Status(http.StatusServiceUnavailable)
return
}
reader := response.Body
contentLength := response.ContentLength
contentType := response.Header.Get("Content-Type")
extraHeaders := map[string]string{
"Content-Disposition": `attachment; filename="gopher.png"`,
}
c.DataFromReader(http.StatusOK, contentLength, contentType, reader, extraHeaders)
})
router.Run()
}5,gin框架核心代码剖析
//gin.New()创建路由代码:
func New() *Engine {
debugPrintWARNINGNew()
engine := &Engine{ //创建一个路由根处理对象,后续的处理皆使用该句柄。
RouterGroup: RouterGroup{
Handlers: nil, //中间件切片集合
basePath: "/",
root: true,
},
FuncMap: template.FuncMap{},
RedirectTrailingSlash: true,
RedirectFixedPath: false,
HandleMethodNotAllowed: false,
ForwardedByClientIP: true,
AppEngine: defaultAppEngine,
UseRawPath: false,
RemoveExtraSlash: false,
UnescapePathValues: true,
MaxMultipartMemory: defaultMultipartMemory,
trees: make(methodTrees, 0, 9), //trees 是最重要的点!!!!负责存储路由和handle方法的映射,采用类似字典树的结构
delims: render.Delims{Left: "{{", Right: "}}"},
secureJsonPrefix: "while(1);",
}
engine.RouterGroup.engine = engine
engine.pool.New = func() interface{} {
return engine.allocateContext()
}
return engine
}
//RouterGroup结构:
type RouterGroup struct {
Handlers HandlersChain //处理函数的切片集合
basePath string
engine *Engine
root bool
}
//实质上是函数类型的结合列表
type HandlerFunc func(*Context)
// HandlersChain defines a HandlerFunc array.
type HandlersChain []HandlerFunc
//创建路由时的流程代码:
func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
absolutePath := group.calculateAbsolutePath(relativePath) //配合之前创建的router的设定的接触路径,得到当前方法路由的的绝对路径信息
handlers = group.combineHandlers(handlers) //重新编排处理函数的切片
group.engine.addRoute(httpMethod, absolutePath, handlers) //将该处理函数添加至路由处理函数数组中
return group.returnObj()
}
//添加路由方法
func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
assert1(path[0] == '/', "path must begin with '/'")
assert1(method != "", "HTTP method can not be empty")
assert1(len(handlers) > 0, "there must be at least one handler")
debugPrintRoute(method, path, handlers)
root := engine.trees.get(method) //该处利用通过创建tree结构管理路由方法,并切一个路由名称匹配一个路由方法构成一个节点
if root == nil {
root = new(node)
root.fullPath = "/"
engine.trees = append(engine.trees, methodTree{method: method, root: root})
}
root.addRoute(path, handlers)
}
//如下为方法tree结构，以及根据方法获取路由树节点,并能从中获取对应的处理函数
type methodTree struct {
method string
root *node
}
type methodTrees []methodTree
func (trees methodTrees) get(method string) *node {
for _, tree := range trees {
if tree.method == method {
return tree.root
}
}
return nil
}6.gin-参数验证器
package main
import (
"fmt"
"github.com/gin-gonic/gin"
"github.com/go-playground/validator/v10"
)
// 标签绑定验证
// 标记集中对应的绑定类型,具体请求过来,可以通过对应的请求进行绑定
type Person struct {
User string `json:"user" form:"user" xml:"user" binding:"required"`
Passwd string `json:"passwd" form:"passwd" xml:"passwd" binding:"required" validate:"passwd"`
}
var (
validate = validator.New()
)
func init() {
if err := validate.RegisterValidation("passwd", validatePasswdFunc); err != nil {
fmt.Println("register validatePasswdFunc is failed")
}
}
// 自定义验证函数,设置validate 以及自定义tag标签
// validatePasswdFunc
func validatePasswdFunc(fl validator.FieldLevel) bool {
pass := fl.Field().String()
if len(pass) > 0 {
return true
}
return false
}
func main() {
r := gin.Default()
// bind JSON
r.POST("/loginJSON", func(c *gin.Context) {
pe := Person{}
if err := c.ShouldBindJSON(&pe); err != nil { // 绑定结构,会调用对应的验证函数验证参数
c.String(400, "Bind pe json is failed !")
}
if pe.User == "**" && pe.Passwd == "***" {
c.String(200, "Bind pe json is success !")
}
})
// bind XML
r.POST("/loginXML", func(c *gin.Context) {
pe := Person{}
if err := c.ShouldBindXML(&pe); err != nil {
fmt.Println("err = ", err.Error())
c.String(400, "Bind pe xml is failed !")
}
if pe.User == "***" && pe.Passwd == "***" {
c.String(200, "Bind pe xml is success !")
}
})
// bind HTML
r.POST("/loginHTML", func(c *gin.Context) {
pe := Person{}
// 此处利用Content-Type Header 推断使用哪个绑定器
if err := c.ShouldBind(&pe); err != nil {
c.String(400, "Bind pe html is failed !")
}
if pe.User == "***" && pe.Passwd == "***" {
c.String(200, "Bind pe html is success !")
}
})
r.Run(":8898")
}如上结构中,制定对应的验证字段信息,在接受请求,validator自带的验证器会对设置了的规则的字段进行较验证，如果有错误,返回相关的信息。
7.自定义验证器
package main
import (
"fmt"
"github.com/go-playground/validator"
"github.com/satori/go.uuid"
"unicode/utf8"
)
type UserInfo struct {
Id string `validate:"uuid"` // UUID 类型
Name string `validate:"checkName"` // 自定义校验
Clear string `validate:"clear"`
Age uint8 `validate:"min=0,max=130"` // 0<=Age<=130
}
// 自定义校验函数
func checkName(f validator.FieldLevel) bool { // FieldLevel contains all the information and helper functions to validate a field
count := utf8.RuneCountInString(f.Field().String()) // 通过utf8编码，获取字符串长度
if count >= 2 && count <= 12 {
return true
}
return false
}
func main() {
validate := validator.New()
// 自定义函数checkName与 struct tag 关联起来
err := validate.RegisterValidation("checkName", checkName)
if err != nil {
fmt.Println("注册失败！")
return
}
err = validate.RegisterValidation("clear", checkName)
if err != nil {
fmt.Println("注册失败！")
return
}
// UUID引用：satori/go.uuid；添加方法：go get github.com/satori/go.uuid
uuid := uuid.Must(uuid.NewV1(), err) // 通过satori/go.uuid，快速生成UUID
fmt.Println("UUID:", uuid)
user := UserInfo{
Id: uuid.String(),
Name: "jiangzhou",
Clear: "c",
Age: 223,
}
err = validate.Struct(user)
if err != nil {
for _, e := range err.(validator.ValidationErrors) {
fmt.Println("错误字段：", e.Field())
fmt.Println("错误值：", e.Value())
fmt.Println("错误tag：", e.Tag())
}
return
}
fmt.Println("校验成功")
}8 swag用法
1.介绍
swag是一个golang通过在代码中对相关的接口方法进行注释标记,通过swag工具生成对应可通过web访问的api文档的一个可视化工具。
2.安装
[root@localhost]# go get -u github.com/swaggo/swag/cmd/swag
[root@localhost]# go get -u github.com/swaggo/gin-swagger
[root@localhost]# go get -u github.com/swaggo/gin-swagger/swaggerFiles安装如上的三个文件包,稍后通过如下命令检查swag是否安装成功。
[root@localhost ~]# swag -v
swag version v1.6.7如果安装完之后,发现没找swag命令,需要配置配置环境变量
mv $GOPATH/bin/swag /usr/local/go/bin
export PATH=$PATH:/usr/local/go/bin在进行测试即可，表明swag安装成功。
3.使用示范
注视格式:
示例1:
@Summary 是对该接口的一个摘要
@Description 是对该接口的一个描述
@Id 是一个全局标识符，所有的接口文档中 Id 不能标注
@Tags 是对接口的标注，同一个 tag 为一组，这样方便我们整理接口
@Version 表明该接口的版本
@Accept 表示该该请求的请求类型
@Produce 表示该该请求的返回类型
@Param 表示参数 分别有以下参数 参数名词 参数类型 数据类型 是否必须 注释 属性(可选参数),参数之间用空格隔开。
@Success 表示请求成功后返回，它有以下参数 请求返回状态码，参数类型，数据类型，注释
@Failure 请求失败后返回，参数同上
@Router 该函数定义了请求路由并且包含路由的请求方式。
for example:
// GetReportData 前端获取上报数据
// @Summary 前端获取上报数据
// @Tags 数据上报
// @Accept json
// @Produce json
// @Param Request body report.StWSGetReportDataReq true " "
// @Success 200 {object} report.StWSGetReportDataRsp
// @Router /api/Report/GetReportData [POST]
func GetReportData(c *gin.Context) {
}说明：
上图有一个错误：
// @router / [Post] 下面不应该有空行
// @Title Get Product list
// @Description Get Product list by some info
// @Success 200 {object} models.ZDTProduct.ProductList
// @Param category_id query int false “category id”
// @Param brand_id query int false “brand id”
// @Param query query string false “query of search”
// @Param segment query string false “segment”
// @Param sort query string false “sort option”
// @Param dir query string false “direction asc or desc”
// @Param offset query int false “offset”
// @Param limit query int false “count limit”
// @Param price query float false “price”
// @Param special_price query bool false “whether this is special price”
// @Param size query string false “size filter”
// @Param color query string false “color filter”
// @Param format query bool false “choose return format”
// @Failure 400 no enough input
// @Failure 500 get products common error
// @router /products [get]
func (c *CMSController) Product() {
}
首先是 CMSController 定义上面的注释，这个是用来显示这个模块的作用。接下来就是每一个函数上面的注释，这里列出来支持的各种注释：
@Title
这个 API 所表达的含义，是一个文本，空格之后的内容全部解析为 title
@Description
这个 API 详细的描述，是一个文本，空格之后的内容全部解析为 Description
@Param
参数，表示需要传递到服务器端的参数，有五列参数，使用空格或者 tab 分割，五个分别表示的含义如下
1.参数名
2.参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
3.参数类型
4.是否必须
5.注释
@Success
成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。
三个参数必须通过空格分隔
Failure
失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息
@router
路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。代码示例:
package main
import (
_ "GoFream/goOther/goMySwag/docs"
"github.com/gin-gonic/gin"
ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"net/http"
)
// @title 测试
// @version 0.0.1
// @description 测试
// @BasePath
func main() {
//dir, _ := os.Getwd()
//fmt.Println("当前路径：", dir)
r := gin.New()
// 文档界面访问URL
// http://127.0.0.1:8980/swagger/index.html
//启动创建swagapi文档路由方式
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// 创建路由组
v1 := r.Group("/api/v1/")
{
v1.GET("/record/:userId", record)
v1.GET("/sayHello/:name", sayHello)
v1.POST("/clsPost/:addr", clsPost)
}
r.Run(":8980")
}
// @获取指定ID记录
// @Description get record by ID
// @Accept json
// @Produce json
// @Param some_id path int true "userId"
// @Success 200 {string} string "ok"
// @Router /api/v1/record/{some_id} [get]
func record(c *gin.Context) {
c.String(http.StatusOK, "ok")
}
// @你好世界
// @Description 你好
// @Accept json
// @Produce json
// @Param name path string true "name"
// @Success 200 {string} string "name,helloWorld"
// @Router /api/v1/sayHello/{name} [get]
func sayHello(c *gin.Context) {
name := c.Param("name")
c.String(http.StatusOK, name+",helloWorld")
}
//@This is Post request
//@Accept json
//@Produce json
//@Param name path string true "clspost"
//@Success 200 {string} string
//@Router /api/v1/clsPost/{name} [post]
func clsPost(c *gin.Context) {
name := c.Param("clsPost")
//c.JSON(200, gin.H{"msg": name})
c.String(200, name)
}在代码工作目录下执行如下命令:
swag init无报错,表示生成文档api成功.
4.访问文档api
启动对应服务,并通过http://127.0.0.1:8980/swagger/index.html 访问api文档服务,如下图所示:
如上三种接口方法,可以通过api结构测试服务接口方法相关信息：
