ginhelper

README

ginhelper

之前接触过Java的Swagger，非常简单易用，但是Golang中一直没有合适的Swagger实现。现在比较流行的方案是使用注释实现，需要手动写注释，总感觉不是特别方便，所以就自己实现了个该工具。坑是挖了很久，刚学go的时候挖的，之后无奈搬砖去写java，一直没机会填坑，最近又重新写go了，所以回来慢慢填坑。

ginhelper支持的功能：

• 整合gin的参数绑定与路由设置
• 非注释自动生成swagger

路由与参数

为了自动绑定参数和生成路由，需要先了解下面几个概念：

• GroupRouter 路由组

type GroupRouter struct {
 Path   string   // 路由组的根路径，与Gin的Group一样，定义一组接口的公共路径
 Name   string   // 路由组的名称
 Routes []*Route // 路由组中的具体路由
}

定义一组相关的路由

• Router 路由

type Route struct {
 Param    Parameter         // 接口的参数实现
 Path     string            // 接口的路径
 Method   string            // 接口的方法
 Handlers []gin.HandlerFunc // 接口的额外处理函数
}

• 参数绑定

为了成功绑定参数，并降低代码的重复度，需要参数实现Parameter接口：

type Parameter interface {
 Bind(c *gin.Context, p Parameter) (err error)  //绑定参数
 Handler(c *gin.Context) (data Data, err error) //执行具体业务
 Result(c *gin.Context, data Data, err error)   //结果返回
}

为了避免不必要的重复实现接口，可以使用结构体嵌入，比如使用内置的BaseParam嵌入。

基本使用

包内包含两种初始化方法：不需要Swagger的func New() *Helper,和自动生成swagger的func NewWithSwagger(swaggerInfo *SwaggerInfo, r GinRouter) *Helper

示例：

// 定义一个Group
var testGroup = &ginhelper.GroupRouter{
 Path: "test",
 Name: "Mytest",
 Routes: []*ginhelper.Route{
  {
   Param:  new(testBodyParam),
   Path:   "/hello/:id",
   Method: "POST",
  }},
}

type FooStruct struct {
 FooA string `binding:"required" `
 FooB *bool  `binding:"required"`
}

// 接口的参数
type testBodyParam struct {
 ginhelper.BaseParam `json:"-"`
 Foo       string    `binding:"required"`
 FooName   string    `json:"fName" binding:"required"`
 FooInt    int       `binding:"required"`
 FooIgnore string    `json:"-"`
 FooStruct
 FooStruct2 FooStruct
 FooStruct3 *FooStruct
}

func (param *testBodyParam) Handler(c *gin.Context) (data ginhelper.Data, err error) {
 return param, nil
}


func Example() {
 router := gin.Default()
 r := router.Group("api")
    // 如果不需要swagger，可以使用New初始化
 h := ginhelper.NewWithSwagger(&ginhelper.SwaggerInfo{
  Description: "swagger test page",
  Title:       "Swagger Test Page",
  Version:     "0.0.1",
  ContactInfoProps: ginhelper.ContactInfoProps{
   Name:  "zzj",
   URL:   "https://zzj.cool",
   Email: "email@zzj.cool",
  },
 }, r)
 h.Add(testGroup, r)
 _ = router.Run(":8888")
}

如果开启了swagger的话，访问http://127.0.0.1:8888/api/swagger即可。

性能测试：

直接使用Gin和使用ginhelper生成的接口，两者性能差别不大：

go test -bench=. -benchmem -run=none

goos: linux
goarch: amd64
pkg: github.com/zzjcool/ginhelper
cpu: AMD Ryzen 5 3400G with Radeon Vega Graphics
BenchmarkHelp-8           236252              4836 ns/op            2258 B/op         38 allocs/op
BenchmarkNorm-8           254684              4765 ns/op            2258 B/op         38 allocs/op
PASS
ok      github.com/zzjcool/ginhelper    2.466s

Documentation

Overview

Package ginhelper brings convenience to development with gin.

Automatically generate swagger documents without comments.

Index

• Constants
• Variables
• func JsonSchemas(typeOf reflect.Type) (schema *spec.Schema)
• type BaseParam
  • func (param *BaseParam) Bind(c *gin.Context, p Parameter) (err error)
  • func (param *BaseParam) Handler(c *gin.Context) (data Data, err error)
  • func (param *BaseParam) Result(c *gin.Context, data Data, err error)
• type ContactInfoProps
• type Data
• type GinRouter
• type GroupRouter
• type Helper
  • func New() *Helper
  • func NewWithSwagger(swaggerInfo *SwaggerInfo, r GinRouter) *Helper
  • func (h *Helper) Add(gh *GroupRouter, r GinRouter)
  • func (h *Helper) View() routerView
• type Parameter
• type Route
  • func (rt *Route) AddHandler(r GinRouter)
• type Swagger
  • func (s *Swagger) AddPath(sp *SwaggerApi)
  • func (s *Swagger) AddTag(tagName, description string)
  • func (s *Swagger) Init()
• type SwaggerApi
• type SwaggerInfo

Examples

• NewWithSwagger

Constants

const (
	MethodGet     = "GET"
	MethodPost    = "POST"
	MethodPut     = "PUT"
	MethodPatch   = "PATCH"
	MethodHead    = "HEAD"
	MethodOptions = "OPTIONS"
	MethodDelete  = "DELETE"
	MethodAny     = "ANY"
)

Variables

var GenHandlerFunc gin.HandlerFunc = nil

Functions

func JsonSchemas

func JsonSchemas(typeOf reflect.Type) (schema *spec.Schema)

Types

type BaseParam

type BaseParam struct {
}

func (*BaseParam) Bind

func (param *BaseParam) Bind(c *gin.Context, p Parameter) (err error)

func (*BaseParam) Handler

func (param *BaseParam) Handler(c *gin.Context) (data Data, err error)

func (*BaseParam) Result

func (param *BaseParam) Result(c *gin.Context, data Data, err error)

type ContactInfoProps

type ContactInfoProps spec.ContactInfoProps

type Data

type Data interface{}

type GinRouter

type GinRouter interface {
	gin.IRoutes
	Group(relativePath string, handlers ...gin.HandlerFunc) *gin.RouterGroup
	BasePath() string
}

type GroupRouter

type GroupRouter struct {
	Path        string   // 路由组的根路径，与Gin的Group一样，定义一组接口的公共路径
	Name        string   // 路由组的名称
	Description string   // 路由组的说明
	Routes      []*Route // 路由组中的具体路由
}

type Helper

type Helper struct {
	Swagger *Swagger
	// contains filtered or unexported fields
}

func New

func New() *Helper

func NewWithSwagger

func NewWithSwagger(swaggerInfo *SwaggerInfo, r GinRouter) *Helper

Example

router := gin.Default()
r := router.Group("api")
h := NewWithSwagger(&SwaggerInfo{
	Description:   "swagger test page",
	Title:         "Swagger Test Page",
	Version:       "0.0.1",
	AuthHeaderKey: "Authorization",
	ContactInfoProps: ContactInfoProps{
		Name:  "zzj",
		URL:   "https://zzj.cool",
		Email: "email@zzj.cool",
	},
}, r)
h.Add(exGroup, r)
_ = router.Run(":12321")

func (*Helper) Add

func (h *Helper) Add(gh *GroupRouter, r GinRouter)

func (*Helper) View

func (h *Helper) View() routerView

type Parameter

type Parameter interface {
	Bind(c *gin.Context, p Parameter) (err error)  //绑定参数
	Handler(c *gin.Context) (data Data, err error) //执行具体业务
	Result(c *gin.Context, data Data, err error)   //结果返回
}

type Route

type Route struct {
	Param    Parameter         // 接口的参数
	Path     string            // 接口的路径
	Method   string            // 接口的方法
	Summary  string            // 接口说明
	Handlers []gin.HandlerFunc // 接口的处理函数
}

func (*Route) AddHandler

func (rt *Route) AddHandler(r GinRouter)

type Swagger

type Swagger struct {
	BasePath string
	Router   GinRouter
	*SwaggerInfo
	Spec *spec.Swagger
}

func (*Swagger) AddPath

func (s *Swagger) AddPath(sp *SwaggerApi)

func (*Swagger) AddTag

func (s *Swagger) AddTag(tagName, description string)

func (*Swagger) Init

func (s *Swagger) Init()

type SwaggerApi

type SwaggerApi struct {
	Path        string
	Method      string
	Description string
	Summary     string
	Tags        []string
	Param       interface{}
}

type SwaggerInfo

type SwaggerInfo struct {
	Description   string
	Title         string
	Version       string
	AuthHeaderKey string
	ContactInfoProps
}