gorest

README

gorest

Quickly build RESTful API in Go with auto-generated OpenAPI 3.1 documentation.

Features

• Auto-parse body and parameters using struct field tags, e.g. json and query.
• Auto-generate OpenAPI 3.1 documentation.

Quickstart

Make sure the environment variables are set (refer to .env.example).

Here's a simple code that demonstrates how to use it:

package main

import (
    "context"
    "log"
    "net/http"

    "github.com/emitra-labs/common/types"
    "github.com/emitra-labs/gorest"
)

func sayHello(ctx context.Context, req *types.Empty) (*types.BasicResponse, error) {
    return &types.BasicResponse{
        Message: "Hello, World!",
    }, nil
}

func main() {
    gorest.Add(http.MethodGet, "/hello", sayHello)

    log.Fatal(gorest.Start())
}

Then, run the program:

go run server.go

Browse to http://localhost:3000/docs and the OpenAPI documentation should be displayed.

Documentation

Index

• func Add[I, O any](method string, path string, f func(context.Context, *I) (*O, error), ...)
• func GetHandler() *echo.Echo
• func Shutdown() error
• func Start() error
• type Config
• type Info
• type OpenAPI
• type RateLimitConfig
  • func RateLimit(count int, period time.Duration) *RateLimitConfig
• type RouteConfig
• type Server
  • func GetServer() *Server

Functions

func Add

func Add[I, O any](
	method string,
	path string,
	f func(context.Context, *I) (*O, error),
	configs ...RouteConfig,
)

func GetHandler

func GetHandler() *echo.Echo

func Shutdown

func Shutdown() error

func Start

func Start() error

Types

type Config

type Config struct {
	Port      int `env:"GOREST_PORT, default=3000"`
	Info      Info
	ServerURL string `env:"GOREST_SERVER_URL, default=http://localhost:3000"`
	RedisURL  string `env:"GOREST_REDIS_URL"`
	PublicKey string `env:"GOREST_PUBLIC_KEY"`
}

type Info

type Info struct {
	Title       string `env:"GOREST_INFO_TITLE, default=My API" json:"title"`
	Description string `env:"GOREST_INFO_DESCRIPTION, default=This is a sample RESTful API server." json:"description,omitempty"`
	Version     string `env:"GOREST_INFO_VERSION, default=1.0.0" json:"version"`
}

type OpenAPI

type OpenAPI struct {
	Reflector *openapi31.Reflector
}

type RateLimitConfig

type RateLimitConfig struct {
	Count  int
	Period time.Duration
}

func RateLimit

func RateLimit(count int, period time.Duration) *RateLimitConfig

type RouteConfig

type RouteConfig struct {
	Summary      string
	Description  string
	Tags         []string
	Authenticate bool
	SuperAdmin   bool
	Permission   string
	RateLimit    *RateLimitConfig
}

type Server

type Server struct {
	Echo    *echo.Echo
	OpenAPI OpenAPI
}

func GetServer

func GetServer() *Server