README
¶
Overview
A lightweight opinionated router to bridge function call and http api. It helps to standardize the way to define input and output of a service.
Features
- Auto generate openapi doc from code reflection
- Use function signature to define input and output
- Type safe without struct tags
Usage
Hello world example: main.go.
Check the examples folder.
Read the tests for details.
Benchmark
Without any optimization, goapi is about 7% slower than echo for the simplest usage. This benchmark is only for avoiding drastic performance changes, the real performance depends on the complexity of the service.
go test -bench=. -benchmem ./lib/bench
goos: darwin
goarch: arm64
pkg: github.com/NaturalSelectionLabs/goapi/lib/bench
Benchmark_goapi-12 34472 33856 ns/op 8448 B/op 114 allocs/op
Benchmark_echo-12 36729 31175 ns/op 6776 B/op 82 allocs/op
PASS
ok github.com/NaturalSelectionLabs/goapi/lib/bench 5.711s
Documentation
¶
Index ¶
- Variables
- func Interface(i any, ts ...any) *vary.Interface
- type ConfigOperation
- type Descriptioner
- type FormatResponse
- type Group
- func (g *Group) Add(method openapi.Method, path string, handler any, opts ...ConfigOperation)
- func (g *Group) DELETE(path string, handler any, opts ...ConfigOperation)
- func (g *Group) GET(path string, handler any, opts ...ConfigOperation)
- func (g *Group) Group(prefix string) *Group
- func (g *Group) HEAD(path string, handler any, opts ...ConfigOperation)
- func (g *Group) Handler(h http.Handler) http.Handler
- func (g *Group) OPTIONS(path string, handler any, opts ...ConfigOperation)
- func (r *Group) OpenAPI(schemas *jschema.Schemas) *openapi.Document
- func (g *Group) PATCH(path string, handler any, opts ...ConfigOperation)
- func (g *Group) POST(path string, handler any, opts ...ConfigOperation)
- func (g *Group) PUT(path string, handler any, opts ...ConfigOperation)
- func (g *Group) Router() *Router
- func (g *Group) Server() http.Handler
- func (g *Group) Shutdown(ctx context.Context) error
- func (g *Group) Start(addr string) error
- func (g *Group) Use(m middlewares.Middleware)
- type InBody
- type InHeader
- type InURL
- type Operation
- type OperationMeta
- type Params
- type Path
- type Response
- type Router
- func (r *Router) Group(prefix string) *Group
- func (r *Router) Handler(next http.Handler) http.Handler
- func (r *Router) OpenAPI(schemas *jschema.Schemas) *openapi.Document
- func (r *Router) ServerHandler() http.Handler
- func (r *Router) Shutdown(ctx context.Context) error
- func (r *Router) Start(addr string) error
- func (r *Router) Use(middlewares ...middlewares.Middleware)
- type StatusAccepted
- type StatusAlreadyReported
- type StatusBadGateway
- type StatusBadRequest
- type StatusConflict
- type StatusContinue
- type StatusCreated
- type StatusEarlyHints
- type StatusExpectationFailed
- type StatusFailedDependency
- type StatusForbidden
- type StatusFound
- type StatusGatewayTimeout
- type StatusGone
- type StatusHTTPVersionNotSupported
- type StatusIMUsed
- type StatusInsufficientStorage
- type StatusInternalServerError
- type StatusLengthRequired
- type StatusLocked
- type StatusLoopDetected
- type StatusMethodNotAllowed
- type StatusMisdirectedRequest
- type StatusMovedPermanently
- type StatusMultiStatus
- type StatusMultipleChoices
- type StatusNetworkAuthenticationRequired
- type StatusNoContent
- type StatusNonAuthoritativeInfo
- type StatusNotAcceptable
- type StatusNotExtended
- type StatusNotFound
- type StatusNotImplemented
- type StatusNotModified
- type StatusOK
- type StatusPartialContent
- type StatusPaymentRequired
- type StatusPermanentRedirect
- type StatusPreconditionFailed
- type StatusPreconditionRequired
- type StatusProcessing
- type StatusProxyAuthRequired
- type StatusRequestEntityTooLarge
- type StatusRequestHeaderFieldsTooLarge
- type StatusRequestTimeout
- type StatusRequestURITooLong
- type StatusRequestedRangeNotSatisfiable
- type StatusResetContent
- type StatusSeeOther
- type StatusServiceUnavailable
- type StatusSwitchingProtocols
- type StatusTeapot
- type StatusTemporaryRedirect
- type StatusTooEarly
- type StatusTooManyRequests
- type StatusUnauthorized
- type StatusUnavailableForLegalReasons
- type StatusUnprocessableEntity
- type StatusUnsupportedMediaType
- type StatusUpgradeRequired
- type StatusUseProxy
- type StatusVariantAlsoNegotiates
Constants ¶
This section is empty.
Variables ¶
View Source
var ErrMissingParam = errors.New("missing parameter in request")
Functions ¶
Types ¶
type ConfigOperation ¶
type ConfigOperation func(op *Operation)
func OperationID ¶ added in v0.3.0
func OperationID(id string) ConfigOperation
OperationID for the operation.
func Security ¶ added in v0.3.1
func Security(security ...map[string][]string) ConfigOperation
Security for the operation.
type Descriptioner ¶ added in v0.3.0
type Descriptioner interface {
Description() string
}
type FormatResponse ¶ added in v0.4.0
type FormatResponse func(openapi.ResponseFormat) any
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
func (*Group) Handler ¶ added in v0.2.0
Use is a shortcut for Router.Handler.
func (*Group) Server ¶
Handler is a shortcut for Router.Handler.
func (*Group) Shutdown ¶ added in v0.2.0
Shutdown is a shortcut for Router.Shutdown.
func (*Group) Start ¶ added in v0.2.0
Start is a shortcut for Router.Start.
type Operation ¶
type Operation struct {
// contains filtered or unexported fields
}
Operation is a handler for a specific HTTP method and path. We use reflection to constrain the handler function signature, to make it follow the openapi spec.
type OperationMeta ¶
type OperationMeta struct {
// Summary is used for display in the openapi UI.
Summary string
// Description is used for display in the openapi UI.
Description string
// OperationID is a unique string used to identify an individual operation.
// This can be used by tools and libraries to provide functionality for
// referencing and calling the operation from different parts of your application.
OperationID string
// Tags are used for grouping operations together for display in the openapi UI.
Tags []string
// Security is a declaration of which security mechanisms can be used for this operation.
Security []map[string][]string
}
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path helps to handle openapi path pattern.
type Response ¶
type Response interface {
// contains filtered or unexported methods
}
Response is an interface that represents a response object.
type Router ¶
type Router struct {
// FormatResponse is a function that formats the response.
// The default format the structs implement [ResponseFormat].
// You can use this function override the default format.
FormatResponse FormatResponse
// Validate the parameters of each request.
Validate func(v interface{}) *openapi.Error
// contains filtered or unexported fields
}
Router itself is a middleware.
func (*Router) OpenAPI ¶
OpenAPI returns the OpenAPI doc of the router. You can use json.Marshal to convert it to a JSON string.
func (*Router) ServerHandler ¶ added in v0.2.0
ServerHandler with a 404 middleware at the end.
func (*Router) Start ¶ added in v0.2.0
Start listen on addr with the Router.ServerHandler.
func (*Router) Use ¶
func (r *Router) Use(middlewares ...middlewares.Middleware)
Use a middleware to the router.
type StatusHTTPVersionNotSupported ¶
type StatusHTTPVersionNotSupported struct{}
StatusHTTPVersionNotSupported 505.
type StatusInsufficientStorage ¶
type StatusInsufficientStorage struct{}
StatusInsufficientStorage 507.
type StatusInternalServerError ¶
type StatusInternalServerError struct{}
StatusInternalServerError 500.
type StatusMisdirectedRequest ¶
type StatusMisdirectedRequest struct{}
StatusMisdirectedRequest 421.
type StatusNetworkAuthenticationRequired ¶
type StatusNetworkAuthenticationRequired struct{}
StatusNetworkAuthenticationRequired 511.
type StatusNonAuthoritativeInfo ¶
type StatusNonAuthoritativeInfo struct{}
StatusNonAuthoritativeInfo 203.
type StatusPreconditionFailed ¶
type StatusPreconditionFailed struct{}
StatusPreconditionFailed 412.
type StatusPreconditionRequired ¶
type StatusPreconditionRequired struct{}
StatusPreconditionRequired 428.
type StatusRequestEntityTooLarge ¶
type StatusRequestEntityTooLarge struct{}
StatusRequestEntityTooLarge 413.
type StatusRequestHeaderFieldsTooLarge ¶
type StatusRequestHeaderFieldsTooLarge struct{}
StatusRequestHeaderFieldsTooLarge 431.
type StatusRequestedRangeNotSatisfiable ¶
type StatusRequestedRangeNotSatisfiable struct{}
StatusRequestedRangeNotSatisfiable 416.
type StatusServiceUnavailable ¶
type StatusServiceUnavailable struct{}
StatusServiceUnavailable 503.
type StatusSwitchingProtocols ¶
type StatusSwitchingProtocols struct{}
StatusSwitchingProtocols 101.
type StatusUnavailableForLegalReasons ¶
type StatusUnavailableForLegalReasons struct{}
StatusUnavailableForLegalReasons 451.
type StatusUnprocessableEntity ¶
type StatusUnprocessableEntity struct{}
StatusUnprocessableEntity 422.
type StatusUnsupportedMediaType ¶
type StatusUnsupportedMediaType struct{}
StatusUnsupportedMediaType 415.
type StatusVariantAlsoNegotiates ¶
type StatusVariantAlsoNegotiates struct{}
StatusVariantAlsoNegotiates 506.
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.