README
¶
gNext Web Framework
gNext is a Golang API-focused framework extending Gin. Offers the API structuring, automates validation and generates documentation. It's compatible with the existing Gin handlers and Gin middlewares. Designed to simplify and boost development of JSON APIs. You can leave generic and boring stuff to gNext and purely focus on the business logic.
Contents
Installation
You can download gNext and install it in your project by running:
go get -u github.com/meteran/gnext
Quick start
This tutorial assumes, that you already have Golang installation and basic knowledge about how to build and run Go programs. If this is your first hit with Go, and you feel you have no idea what is happening here, please read how to get started with Go.
Ok, so let's create a project:
mkdir gnext-example
cd gnext-example
go mod init example.com/gnext
go get github.com/meteran/gnext
Create a file example.go and fill it up with the following code:
package main
import "github.com/meteran/gnext"
func main() {
r := gnext.Router()
r.GET("/example", func() string {
return "Hello World!"
})
_ = r.Run()
}
Run it:
go run example
Now you can visit this link in your browser: http://localhost:8080/example
Yes, yes... of course it works, but that's boring... Let's open this page: http://localhost:8080/docs
Whoa, that was amazing, ...but not very useful.
Let's try some real example. With request and response. We can modify our handler to use structures:
package main
import "github.com/meteran/gnext"
func main() {
r := gnext.Router()
r.POST("/example", handler)
_ = r.Run()
}
type MyRequest struct {
Id int `json:"id" binding:"required"`
Name string `json:"name"`
}
type MyResponse struct {
Result string `json:"result"`
}
func handler(req *MyRequest) *MyResponse {
return &MyResponse{Result: req.Name}
}
Restart the server and visit the docs page. You can see that request and response of POST /example endpoint are
documented. That's the real power!
The POST request without required id now fails with the validation error:
curl --request POST http://localhost:8080/example --data '{"name": "some name"}'
gives output:
{
"message": "validation error",
"details": [
"field validation for 'id' failed on the 'required' tag with value ''"
],
"success": false
}
the valid request:
curl --request POST http://localhost:8080/example --data '{"name": "some name", "id": 4}'
gives us the expected response:
{
"result": "some name"
}
Congratulations! Now you are prepared for the fast forwarding development of your great API.
Documentation
¶
Index ¶
- func DefaultErrorHandler(err error) (status Status, response *DefaultErrorResponse)
- type Body
- type BodyInterface
- type DefaultErrorResponse
- type ErrorResponse
- type HandlerPanicked
- type HandlerWrapper
- type Headers
- type HeadersInterface
- type IRouter
- type IRoutes
- type Middleware
- type NotFound
- type Query
- type QueryInterface
- type Response
- type ResponseInterface
- type RootRouter
- func (g *RootRouter) Any(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) DELETE(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (r *RootRouter) Engine() *gin.Engine
- func (g *RootRouter) GET(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) Group(prefix string, _ ...*docs.Endpoint) IRouter
- func (g *RootRouter) HEAD(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) Handle(method string, path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) OPTIONS(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) OnError(errorHandler interface{}) IRoutes
- func (g *RootRouter) PATCH(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) POST(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) PUT(path string, handler interface{}, doc ...*docs.Endpoint) IRoutes
- func (g *RootRouter) RawRouter() gin.IRouter
- func (r *RootRouter) Run(address ...string) error
- func (r *RootRouter) ServeHTTP(response http.ResponseWriter, req *http.Request)
- func (g *RootRouter) Use(middleware Middleware) IRoutes
- type Status
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultErrorHandler ¶ added in v0.2.0
func DefaultErrorHandler(err error) (status Status, response *DefaultErrorResponse)
Types ¶
type BodyInterface ¶
type BodyInterface interface {
GnBody()
}
type DefaultErrorResponse ¶ added in v0.2.0
type DefaultErrorResponse struct {
ErrorResponse `default_status:"500" status_codes:"4XX,5XX"`
Message string `json:"message"`
Details []string `json:"details"`
Success bool `json:"success"`
}
type ErrorResponse ¶ added in v0.2.0
type ErrorResponse struct{}
type HandlerPanicked ¶ added in v0.2.0
type HandlerPanicked struct {
Value interface{}
StackTrace []byte
}
func (*HandlerPanicked) Error ¶ added in v0.2.0
func (e *HandlerPanicked) Error() string
type HandlerWrapper ¶
type HandlerWrapper struct {
// contains filtered or unexported fields
}
func WrapHandler ¶
type HeadersInterface ¶
type HeadersInterface interface {
GnHeaders()
}
type IRoutes ¶
type IRoutes interface {
Use(Middleware) IRoutes
Handle(string, string, interface{}, ...*docs.Endpoint) IRoutes
Any(string, interface{}, ...*docs.Endpoint) IRoutes
GET(string, interface{}, ...*docs.Endpoint) IRoutes
POST(string, interface{}, ...*docs.Endpoint) IRoutes
DELETE(string, interface{}, ...*docs.Endpoint) IRoutes
PATCH(string, interface{}, ...*docs.Endpoint) IRoutes
PUT(string, interface{}, ...*docs.Endpoint) IRoutes
OPTIONS(string, interface{}, ...*docs.Endpoint) IRoutes
HEAD(string, interface{}, ...*docs.Endpoint) IRoutes
}
type Middleware ¶
type Middleware struct {
Before interface{}
After interface{}
}
type QueryInterface ¶
type QueryInterface interface {
GnQuery()
}
type Response ¶
type Response struct{}
func (Response) GnResponse ¶ added in v0.8.0
func (m Response) GnResponse()
type ResponseInterface ¶
type ResponseInterface interface {
GnResponse()
}
type RootRouter ¶ added in v0.2.0
type RootRouter struct {
// contains filtered or unexported fields
}
RootRouter is a main struct of the module. All other operations are made using this router.
func Router ¶
func Router(docsOptions ...*docs.Options) *RootRouter
Router is a RootRouter constructor. It gets one optional parameter *docs.Options. If passed, all non-empty fields from this struct will be used to initialize the documentation.
func (*RootRouter) Engine ¶ added in v0.2.0
func (r *RootRouter) Engine() *gin.Engine
Engine returns the raw Gin engine. It can be used to add Gin-native handlers or middlewares.
Note: handlers and middlewares attached directly to the raw engine bypasses the gNext core. Because of that they won't be included in the docs nor validation mechanism.
func (*RootRouter) OnError ¶ added in v0.2.0
func (g *RootRouter) OnError(errorHandler interface{}) IRoutes
func (*RootRouter) Run ¶ added in v0.2.0
func (r *RootRouter) Run(address ...string) error
Run starts the http server. It takes optional address parameters. The number of parameters is meaningful:
- 0 - defaults to ":8080".
- 1 - means the given address is either a full address in form 'host:port` or, if doesn't contain ':', a port.
- 2 - first parameter is a host, the latter one is a port.
- 3+ - invalid address.
func (*RootRouter) ServeHTTP ¶ added in v0.7.0
func (r *RootRouter) ServeHTTP(response http.ResponseWriter, req *http.Request)
ServeHTTP executes the request from `req`, runs handlers and writes response to the `response` parameter. It is typically used testing purpose.
func (*RootRouter) Use ¶ added in v0.2.0
func (g *RootRouter) Use(middleware Middleware) IRoutes
Source Files
Directories