shiftapi

README

ShiftAPI

Quickly write RESTful APIs in go with automatic openapi schema generation.

NOTE: THIS IS AN EXPERIMENT

This project is highly experimental -- the API is likely to change (currently only basic post requests are even implemented). This is in no way production ready.

This project was inspired by the simplicity of FastAPI.

Due to limitations of typing in go this library will probably not be production ready pre go 1.18 as handlers must be passed as interface{}s and validated at runtime (Scary I know! 😱). Once generics hit I hope to rewrite the handler implementation to restore compile time type checking & safety.

Installation

go get github.com/fcjr/shiftapi

Usage

package main

import (
	"log"
	"net/http"

	"github.com/fcjr/shiftapi"
)

type Person struct {
	Name string `json:"name"`
}

type Greeting struct {
	Hello string `json:"hello"`
}

// This is your http handler!
// ShiftAPI is responsible for marshalling the request body
//  and marshalling the return value.
func greeter(p *Person) (*Greeting, *shiftapi.Error) {
	return &Greeting{
		Hello: p.Name,
	}, nil
}

func main() {

	api := shiftapi.New(&shiftapi.Params{
		SchemaInfo: &shiftapi.SchemaParams{
			Title: "Greeter Demo API",
		},
	})

	err := api.POST("/greet", greeter, http.StatusOK, &shiftapi.HandlerOpts{
		Summary:     "Greeter Method",
		Description: "It greets you by name.",
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Fatal(api.Serve())
	// redoc will be served at http://localhost:8080/docs
}

Documentation

Index

• type Error
• type HandlerOpts
• type Params
• type SchemaParams
• type ShiftAPI
  • func New(params *Params) *ShiftAPI
  • func (s *ShiftAPI) POST(path string, handler interface{}, status int, opts *HandlerOpts) error
  • func (s *ShiftAPI) Serve() error

Types

type Error

type Error struct {
	Code int
	Body []byte
}

type HandlerOpts

type HandlerOpts struct {
	Summary     string
	Description string
}

type Params

type Params struct {
	SchemaInfo *SchemaParams
}

type SchemaParams

type SchemaParams struct {
	Title string
}

type ShiftAPI

type ShiftAPI struct {
	// contains filtered or unexported fields
}

func New

func New(params *Params) *ShiftAPI

func (*ShiftAPI) POST

func (s *ShiftAPI) POST(path string, handler interface{}, status int, opts *HandlerOpts) error

func (*ShiftAPI) Serve

func (s *ShiftAPI) Serve() error