soda

package module
v2.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2024 License: MIT Imports: 18 Imported by: 0

README

Soda

soda := OpenAPI3.1 + fiber

Example

package main
import (
 "fmt"

 "github.com/gofiber/fiber/v2"
 "github.com/gofiber/fiber/v2/middleware/logger"
 "github.com/gofiber/fiber/v2/middleware/requestid"
 "github.com/neo-f/soda"
)

type Auth struct {
 Token string `header:"Authorization" oai:"description=some JWT Token"`
}

type ExParameters struct {
 Auth            // the embed struct will be parsed as well
 ID     int      `path:"id"      oai:"description=some id"                           `
 Q      []string `query:"q"      oai:"description=support list parameters"            `
 Limit  int      `query:"limit"  oai:"description=limit params"                      `
 Offset int8     `query:"offset" oai:"description=offset params"                     `
}

type ExBody struct {
 Body struct {
  ID     int      `json:"id"     validate:"required" oai:"description=this is the id"`
  Q      []string `json:"q"      validate:"required" oai:"description=the query to search"`
  Limit  int      `json:"limit"  validate:"required" oai:"description=limit;maximum=20"`
  Offset int      `json:"offset" validate:"required" oai:"description=offset"`
 } `body:"json"`
}

type ExampleResponse struct {
 Parameters  *ExParameters `json:"parameters"`
 RequestBody *ExBody       `json:"request_body"`
}
type ErrorResponse struct {
 Error string `json:"error"`
}

func exampleGet(c *fiber.Ctx) error {
 params := soda.GetInput[ExParameters](c)
 fmt.Println(params.Token, params.Limit, params.Offset, params.Q)
 return c.Status(200).JSON(ExampleResponse{
  Parameters: params,
 })
}

func examplePost(c *fiber.Ctx) error {
 input := soda.GetInput[ExBody](c)
 fmt.Println(input.Body.Limit, input.Body.Offset, input.Body.Q)
 return c.Status(200).JSON(ExampleResponse{
  RequestBody: input,
 })
}

func main() {
 app := soda.New(fiber.New()).
  AddJSONSpec("/openapi.json").
  AddUI("/", soda.UIStoplightElement).
  AddUI("/swagger", soda.UISwaggerUI)

 app.Fiber.Use(logger.New(), requestid.New())

 app.Get("/test/:id", exampleGet).
  SetInput(ExParameters{}).
  AddJSONResponse(200, ExampleResponse{}).
  AddJSONResponse(400, ErrorResponse{}).OK()

 app.Post("/test", examplePost).
  SetInput(ExBody{}).
  AddJSONResponse(200, ExampleResponse{}).
  AddJSONResponse(400, ErrorResponse{}).OK()
 _ = app.Fiber.Listen(":8080")
}

check your openapi3 spec file at http://localhost:8080/openapi.json

and embed openapi3 renderer

Documentation

Index

Constants

View Source 
const (
	KeyInput ck = "soda::input"
)

Variables

View Source 
var (
	OpenAPITag        = "oai"
	SeparatorProp     = ";"
	SeparatorPropItem = ","
)
View Source 
var (
	UISwaggerUI        = builtinUIRender{/* contains filtered or unexported fields */}
	UIRapiDoc          = builtinUIRender{/* contains filtered or unexported fields */}
	UIStoplightElement = builtinUIRender{/* contains filtered or unexported fields */}
	UIRedoc            = builtinUIRender{/* contains filtered or unexported fields */}
)

Functions

func GenerateSchema 

func GenerateSchema(model any, nameTag string) *base.Schema

GenerateSchema generates an OpenAPI schema for a given model using the given name tag. It takes in the model to generate a schema for and a name tag to use for naming properties. It returns a *spec.Schema that represents the generated schema.

func GetInput 

func GetInput[T any](c *http.Request) *T

GetInput gets the input value from the http request.

func NewAPIKeySecurityScheme 

func NewAPIKeySecurityScheme(in string, name string, description ...string) *v3.SecurityScheme

func NewGenerator 

func NewGenerator() *generator

Create a new generator.

func NewJWTSecurityScheme 

func NewJWTSecurityScheme(description ...string) *v3.SecurityScheme

Types

type Engine 

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

func New 

func New() *Engine

func NewWith 

func NewWith(router chi.Router) *Engine

func (Engine) AddJSONResponse 

func (r Engine) AddJSONResponse(code int, model any, description ...string) Router

func (Engine) AddSecurity 

func (r Engine) AddSecurity(securityName string, scheme *v3.SecurityScheme) Router

func (Engine) AddTags 

func (r Engine) AddTags(tags ...string) Router

func (Engine) Delete 

func (r Engine) Delete(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Get 

func (r Engine) Get(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Group 

func (r Engine) Group(fn func(Router)) Router

func (Engine) Head 

func (r Engine) Head(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) HttpHandler 

func (r Engine) HttpHandler() chi.Router

func (Engine) Method 

func (r Engine) Method(method string, pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Mount 

func (r Engine) Mount(pattern string, sub *Engine)

func (Engine) OnAfterBind 

func (r Engine) OnAfterBind(hook HookAfterBind) Router

func (Engine) OnBeforeBind 

func (r Engine) OnBeforeBind(hook HookBeforeBind) Router

func (*Engine) OpenAPI 

func (e *Engine) OpenAPI() *v3.Document

func (Engine) Options 

func (r Engine) Options(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Patch 

func (r Engine) Patch(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Post 

func (r Engine) Post(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Put 

func (r Engine) Put(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Route 

func (r Engine) Route(pattern string, fn func(sub Router)) Router

func (*Engine) ServeDocUI added in v2.0.5 

func (e *Engine) ServeDocUI(pattern string, ui UIRender) *Engine

func (*Engine) ServeSpecJSON added in v2.0.5 

func (e *Engine) ServeSpecJSON(pattern string) *Engine

func (*Engine) ServeSpecYAML added in v2.0.5 

func (e *Engine) ServeSpecYAML(pattern string) *Engine

func (Engine) SetDeprecated 

func (r Engine) SetDeprecated(deprecated bool) Router

func (Engine) SetIgnoreAPIDoc 

func (r Engine) SetIgnoreAPIDoc(ignore bool) Router

SetIgnoreAPIDoc implements Router.

func (Engine) Trace 

func (r Engine) Trace(pattern string, handler http.HandlerFunc) *OperationBuilder

func (Engine) Use 

func (r Engine) Use(middlewares ...func(http.Handler) http.Handler)

func (Engine) With 

func (r Engine) With(middlewares ...func(http.Handler) http.Handler) Router

type HookAfterBind 

type HookAfterBind func(w http.ResponseWriter, r *http.Request, input any) (doNext bool)

HookAfterBind is a function type that is called after binding the request. It returns a boolean indicating whether to continue the process.

type HookBeforeBind 

type HookBeforeBind func(w http.ResponseWriter, r *http.Request) (doNext bool)

HookBeforeBind is a function type that is called before binding the request. It returns a boolean indicating whether to continue the process.

type OperationBuilder 

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

OperationBuilder is a struct that helps in building an operation.

func (*OperationBuilder) AddJSONResponse 

func (op *OperationBuilder) AddJSONResponse(code int, model any, description ...string) *OperationBuilder

AddJSONResponse adds a JSON response to the operation.

func (*OperationBuilder) AddSecurity 

func (op *OperationBuilder) AddSecurity(securityName string, scheme *v3.SecurityScheme) *OperationBuilder

AddSecurity adds a security scheme to the operation.

func (*OperationBuilder) AddTags 

func (op *OperationBuilder) AddTags(tags ...string) *OperationBuilder

AddTags adds tags to the operation.

func (*OperationBuilder) OK 

func (op *OperationBuilder) OK()

OK finalizes the operation building process.

func (*OperationBuilder) OnAfterBind 

func (op *OperationBuilder) OnAfterBind(hook HookAfterBind) *OperationBuilder

OnAfterBind adds a hook that is called after binding the request.

func (*OperationBuilder) OnBeforeBind 

func (op *OperationBuilder) OnBeforeBind(hook HookBeforeBind) *OperationBuilder

OnBeforeBind adds a hook that is called before binding the request.

func (*OperationBuilder) SetDeprecated 

func (op *OperationBuilder) SetDeprecated(deprecated *bool) *OperationBuilder

SetDeprecated marks the operation as deprecated or not.

func (*OperationBuilder) SetDescription 

func (op *OperationBuilder) SetDescription(desc string) *OperationBuilder

SetDescription sets the description of the operation.

func (*OperationBuilder) SetIgnoreAPIDoc 

func (op *OperationBuilder) SetIgnoreAPIDoc(ignore bool) *OperationBuilder

SetIgnoreAPIDoc sets whether to ignore the operation when generating the API doc.

func (*OperationBuilder) SetInput 

func (op *OperationBuilder) SetInput(input any) *OperationBuilder

SetInput sets the input type for the operation.

func (*OperationBuilder) SetOperationID 

func (op *OperationBuilder) SetOperationID(id string) *OperationBuilder

SetOperationID sets the operation ID of the operation.

func (*OperationBuilder) SetSummary 

func (op *OperationBuilder) SetSummary(summary string) *OperationBuilder

SetSummary sets the summary of the operation.

type Router 

type Router interface {
	// HttpHandler returns the underlying chi.Router.
	HttpHandler() chi.Router

	// Method registers a handler function for the specified HTTP method and pattern.
	Method(method string, pattern string, handler http.HandlerFunc) *OperationBuilder

	// Delete registers a handler function for the DELETE HTTP method and pattern.
	Delete(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Get registers a handler function for the GET HTTP method and pattern.
	Get(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Head registers a handler function for the HEAD HTTP method and pattern.
	Head(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Options registers a handler function for the OPTIONS HTTP method and pattern.
	Options(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Patch registers a handler function for the PATCH HTTP method and pattern.
	Patch(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Post registers a handler function for the POST HTTP method and pattern.
	Post(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Put registers a handler function for the PUT HTTP method and pattern.
	Put(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Trace registers a handler function for the TRACE HTTP method and pattern.
	Trace(pattern string, handler http.HandlerFunc) *OperationBuilder

	// Mount mounts a sub-router under the specified pattern.
	Mount(pattern string, sub *Engine)

	// Group creates a new sub-router and applies the provided function to it.
	Group(fn func(Router)) Router

	// With adds the specified middlewares to the router.
	With(middlewares ...func(http.Handler) http.Handler) Router

	// Route creates a new sub-router under the specified pattern and applies the provided function to it.
	Route(pattern string, fn func(sub Router)) Router

	// Use adds the specified middlewares to the router.
	Use(middlewares ...func(http.Handler) http.Handler)

	// AddTags adds the specified tags to the router.
	AddTags(tags ...string) Router

	// AddSecurity adds the specified security scheme to the router.
	AddSecurity(securityName string, scheme *v3.SecurityScheme) Router

	// AddJSONResponse adds a JSON response definition to the router.
	AddJSONResponse(code int, model any, description ...string) Router

	// SetDeprecated sets whether the router is deprecated or not.
	SetDeprecated(deprecated bool) Router

	// SetIgnoreAPIDoc sets whether the router should be ignored in the API documentation.
	SetIgnoreAPIDoc(ignore bool) Router

	// OnAfterBind sets a hook function to be called after binding the request.
	OnAfterBind(hook HookAfterBind) Router

	// OnBeforeBind sets a hook function to be called before binding the request.
	OnBeforeBind(hook HookBeforeBind) Router
}

Router is an interface that represents a HTTP router.

type UIRender 

type UIRender interface {
	Render(doc *v3.Document) string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.