egs

README

egs

Egs is a Go framework based on Gin, designed to quickly generate Swagger documentation, which means "Easy Gin Swagger"

Featurs

• Fast and efficient routing with Gin
• Automatic generation of Swagger documentation

Why I build this project?

I once wanted to find a convenient way to generate Swagger documentation for Gin web services, and then I found this project SwaGin. But I found that the project has not been updated sometime and there are some problems with the code. Such as the following:

• panic when the response struct has pointers
• group doesn't work when use middlewares
• don't register components for structs which results in the Swagger JSON containing many duplicated information
• don't support enum type
• don't support OAuth and OIDC authentication
• can't register request struct
• wrong field value of apiKey authentication and don't support cookie and query api key
• authentications have the same name which causes

So I decided to rewrite many codes and fix the above problems.

Installation

go get -u github.com/Yuukirn/egs

Usage

1. Import the package in your Go file:

import "github.com/Yuukirn/egs"

1. Define a struct for the request parameters:

type TestStruct struct {
	ID    string `uri:"id" validate:"required" json:"id"`
	Name  string `form:"name" json:"name"`
	Age   int    `form:"age" json:"age"`
	Token string `header:"authorization" validate:"required" json:"token"`
}

Egs uses validator to validate the request parameters, so you need to add validate tags to the struct fields. And egs will bind the struct for you. 3. Define the api

func TestApi(c *gin.Context, req TestStruct) {
	bytes, err := json.Marshal(req)
	if err != nil {
		panic(err)
	}
	println(string(bytes))
	c.JSON(http.StatusOK, TestResp{
		Code: 200,
		Msg:  "OK",
	})
}

Note that the first parameter is *gin.Context, and the second parameter is the request struct. 4. Define the router

var test = router.NewRouter(TestApi,
	router.Tags("test"),
	router.Summary("test summary"),
	router.Desc("test desc"),
	router.Req(router.Request{
		Model: &TestStruct{},
	}),
	router.Resp(router.Response{
		"200": router.ResponseItem{
			Model: &TestResp{},
		},
	}),
)

You can also add other metadata here. 5. Register the router

testGroup := app.Group("test", egs.Handlers(testMiddleware), egs.Security(jwtAuth))
testGroup.POST("/:id", test)

You can find an example in the examples folder. Run the example and enter http://127.0.0.1:8080/docs then you can see the swagger docs like this.

TODO

• Add OAuth and OIDC authentication

ThanksTo

• SwaGin Swagger + Gin = SwaGin, a web framework based on Gin and Swagger
• kin-openapi, OpenAPI 3.0 implementation for Go (parsing, converting, validation, and more).
• Gin, an HTTP web framework written in Go (Golang).

Documentation

Index

• Constants
• type Egs
  • func New(swagger *Swagger) *Egs
  • func (e *Egs) DELETE(path string, r *router.Router)
  • func (e *Egs) GET(path string, r *router.Router)
  • func (e *Egs) Group(path string, options ...GroupOption) *Group
  • func (e *Egs) HEAD(path string, r *router.Router)
  • func (e *Egs) OPTIONS(path string, r *router.Router)
  • func (e *Egs) PATCH(path string, r *router.Router)
  • func (e *Egs) POST(path string, r *router.Router)
  • func (e *Egs) PUT(path string, r *router.Router)
  • func (e *Egs) Run(addr ...string) error
  • func (e *Egs) Use(middlewares ...gin.HandlerFunc) gin.IRoutes
• type Group
  • func (g *Group) DELETE(path string, r *router.Router)
  • func (g *Group) GET(path string, r *router.Router)
  • func (g *Group) Group(path string, options ...GroupOption) *Group
  • func (g *Group) HEAD(path string, r *router.Router)
  • func (g *Group) OPTIONS(path string, r *router.Router)
  • func (g *Group) PATCH(path string, r *router.Router)
  • func (g *Group) POST(path string, r *router.Router)
  • func (g *Group) PUT(path string, r *router.Router)
  • func (g *Group) Use(middleware ...gin.HandlerFunc) gin.IRoutes
• type GroupOption
  • func Handlers(handlers ...gin.HandlerFunc) GroupOption
  • func Security(securities ...security.Security) GroupOption
  • func Tags(tags string) GroupOption
• type RouterMap
• type Swagger
  • func NewSwagger(title, desc, version string) *Swagger
  • func (swagger *Swagger) BuildOpenAPI()
  • func (swagger *Swagger) MarshalJSON() ([]byte, error)
  • func (swagger *Swagger) MarshalYaml() ([]byte, error)

Constants

const (
	DEFAULT     = "default"
	BINDING     = "binding"
	DESCRIPTION = "description"
	QUERY       = "query"
	FORM        = "form"
	URI         = "uri"
	HEADER      = "header"
	COOKIE      = "cookie"
	JSON        = "json"
)

Types

type Egs

type Egs struct {
	*gin.Engine

	// Swagger is used to construct swagger json
	Swagger *Swagger

	Routers RouterMap
}

func New

func New(swagger *Swagger) *Egs

func (*Egs) DELETE

func (e *Egs) DELETE(path string, r *router.Router)

func (*Egs) GET

func (e *Egs) GET(path string, r *router.Router)

func (*Egs) Group

func (e *Egs) Group(path string, options ...GroupOption) *Group

func (*Egs) HEAD

func (e *Egs) HEAD(path string, r *router.Router)

func (*Egs) OPTIONS

func (e *Egs) OPTIONS(path string, r *router.Router)

func (*Egs) PATCH

func (e *Egs) PATCH(path string, r *router.Router)

func (*Egs) POST

func (e *Egs) POST(path string, r *router.Router)

func (*Egs) PUT

func (e *Egs) PUT(path string, r *router.Router)

func (*Egs) Run

func (e *Egs) Run(addr ...string) error

func (*Egs) Use

func (e *Egs) Use(middlewares ...gin.HandlerFunc) gin.IRoutes

type Group

type Group struct {
	Egs         *Egs
	Path        string
	Tags        []string
	RouterGroup *gin.RouterGroup

	// middlewares
	Handlers   []gin.HandlerFunc
	Securities []security.Security
}

func (*Group) DELETE

func (g *Group) DELETE(path string, r *router.Router)

func (*Group) GET

func (g *Group) GET(path string, r *router.Router)

func (*Group) Group

func (g *Group) Group(path string, options ...GroupOption) *Group

func (*Group) HEAD

func (g *Group) HEAD(path string, r *router.Router)

func (*Group) OPTIONS

func (g *Group) OPTIONS(path string, r *router.Router)

func (*Group) PATCH

func (g *Group) PATCH(path string, r *router.Router)

func (*Group) POST

func (g *Group) POST(path string, r *router.Router)

func (*Group) PUT

func (g *Group) PUT(path string, r *router.Router)

func (*Group) Use

func (g *Group) Use(middleware ...gin.HandlerFunc) gin.IRoutes

type GroupOption

type GroupOption func(group *Group)

func Handlers

func Handlers(handlers ...gin.HandlerFunc) GroupOption

func Security

func Security(securities ...security.Security) GroupOption

func Tags

func Tags(tags string) GroupOption

type RouterMap

type RouterMap map[*gin.RouterGroup]map[string]map[string]*router.Router

type Swagger

type Swagger struct {
	// metadata
	Title          string
	Description    string
	TermsOfService string
	Contact        *openapi3.Contact
	License        *openapi3.License
	Version        string

	DocsUrl    string
	OpenAPIUrl string
	RedocUrl   string
	OpenAPI    *openapi3.T

	Servers openapi3.Servers

	Routers RouterMap

	SwaggerOptions map[string]any
	RedocOptions   map[string]any
}

func NewSwagger

func NewSwagger(title, desc, version string) *Swagger

func (*Swagger) BuildOpenAPI

func (swagger *Swagger) BuildOpenAPI()

func (*Swagger) MarshalJSON

func (swagger *Swagger) MarshalJSON() ([]byte, error)

func (*Swagger) MarshalYaml

func (swagger *Swagger) MarshalYaml() ([]byte, error)