soda

package module
v2.1.0 Latest Latest
Warning

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

Go to latest
Published: Apr 8, 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
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL