soda

package module
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2023 License: MIT Imports: 16 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 = "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 interface{}, nameTag string) *spec.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 *fiber.Ctx) *T

func NewGenerator 

func NewGenerator() *generator

Create a new generator.

Types

type Group added in v1.5.0 

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

func (*Group) AddJSONResponse added in v1.6.0 

func (g *Group) AddJSONResponse(status int, model interface{}, description ...string) *Group

AddJSONResponse adds a JSON response to the groups.

func (*Group) AddSecurity added in v1.5.0 

func (g *Group) AddSecurity(name string, scheme *spec.SecurityScheme) *Group

AddSecurity adds a security scheme to the group.

func (*Group) AddTags added in v1.5.0 

func (g *Group) AddTags(tags ...string) *Group

AddTags adds tags to the operation.

func (*Group) Delete added in v1.5.0 

func (g *Group) Delete(path string, handlers ...fiber.Handler) *OperationBuilder

Delete adds a DELETE operation.

func (*Group) Fiber added in v1.5.0 

func (g *Group) Fiber() *fiber.App

Fiber returns the underlying fiber app.

func (*Group) Get added in v1.5.0 

func (g *Group) Get(path string, handlers ...fiber.Handler) *OperationBuilder

Get adds a GET operation.

func (*Group) Group added in v1.5.0 

func (g *Group) Group(prefix string, handlers ...fiber.Handler) *Group

Group creates a new sub-group with optional prefix and middleware.

func (*Group) Head added in v1.5.0 

func (g *Group) Head(path string, handlers ...fiber.Handler) *OperationBuilder

Head adds a HEAD operation.

func (*Group) OnAfterBind added in v1.5.0 

func (g *Group) OnAfterBind(hook HookAfterBind) *Group

OnAfterBind adds a hook to be executed after the operation is bound.

func (*Group) OnBeforeBind added in v1.6.0 

func (g *Group) OnBeforeBind(hook HookBeforeBind) *Group

OnBeforeBind adds a hook to be executed after the operation is bound.

func (*Group) Operation added in v1.5.0 

func (g *Group) Operation(path, method string, handlers ...fiber.Handler) *OperationBuilder

Operation adds an operation.

func (*Group) Options added in v1.5.0 

func (g *Group) Options(path string, handlers ...fiber.Handler) *OperationBuilder

Options adds an OPTIONS operation.

func (*Group) Patch added in v1.5.0 

func (g *Group) Patch(path string, handlers ...fiber.Handler) *OperationBuilder

Patch adds a PATCH operation.

func (*Group) Post added in v1.5.0 

func (g *Group) Post(path string, handlers ...fiber.Handler) *OperationBuilder

Post adds a POST operation.

func (*Group) Put added in v1.5.0 

func (g *Group) Put(path string, handlers ...fiber.Handler) *OperationBuilder

Put adds a PUT operation.

func (*Group) SetDeprecated added in v1.5.0 

func (g *Group) SetDeprecated(deprecated bool) *Group

SetDeprecated sets the deprecated flag for the group.

func (*Group) Trace added in v1.5.0 

func (g *Group) Trace(path string, handlers ...fiber.Handler) *OperationBuilder

Trace adds a TRACE operation.

type HookAfterBind added in v1.5.0 

type HookAfterBind func(c *fiber.Ctx, input interface{}) error

type HookBeforeBind added in v1.6.0 

type HookBeforeBind func(c *fiber.Ctx) error

type OperationBuilder 

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

OperationBuilder is a builder for a single operation.

func (*OperationBuilder) AddJSONResponse 

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

AddJSONResponse adds a JSON response to the operation's responses. If model is not nil, a JSON response is generated for the model type. If model is nil, a JSON response is generated with no schema.

func (*OperationBuilder) AddSecurity 

func (op *OperationBuilder) AddSecurity(name string, scheme *spec.SecurityScheme) *OperationBuilder

AddJWTSecurity adds JWT authentication to this operation with the given validators.

func (*OperationBuilder) AddTags 

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

AddTags add tags to the operation.

func (*OperationBuilder) OK 

func (op *OperationBuilder) OK() *OperationBuilder

func (*OperationBuilder) OnAfterBind added in v1.5.0 

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

func (*OperationBuilder) OnBeforeBind added in v1.6.0 

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

func (*OperationBuilder) SetDeprecated 

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

SetDeprecated marks the operation as deprecated.

func (*OperationBuilder) SetDescription 

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

SetDescription sets the operation description.

func (*OperationBuilder) SetInput 

func (op *OperationBuilder) SetInput(input interface{}) *OperationBuilder

SetInput sets the input for this operation. The input must be a pointer to a struct. If the struct has a field with the `body:"<media type>"` tag, that field is used for the request body. Otherwise, the struct is used for parameters.

func (*OperationBuilder) SetOperationID 

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

SetSummary sets the operation-id.

func (*OperationBuilder) SetSummary 

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

SetSummary sets the operation summary.

type Soda 

type Soda struct {
	Fiber *fiber.App
	// contains filtered or unexported fields
}

Soda is the main class of the package. It contains the spec and the fiber app.

func New 

func New(app *fiber.App) *Soda

New creates a Soda instance.

func (*Soda) AddJSONSpec 

func (s *Soda) AddJSONSpec(path string) *Soda

AddJSONSpec adds the OpenAPI spec at the given path in JSON format.

func (*Soda) AddUI 

func (s *Soda) AddUI(path string, ui UIRender) *Soda

AddUI adds a UI to the given path, rendering the OpenAPI spec.

func (*Soda) AddYAMLSpec 

func (s *Soda) AddYAMLSpec(path string) *Soda

AddYAMLSpec adds the OpenAPI spec at the given path in YAML format.

func (*Soda) Delete 

func (s *Soda) Delete(path string, handlers ...fiber.Handler) *OperationBuilder

Delete adds a DELETE operation.

func (*Soda) Get 

func (s *Soda) Get(path string, handlers ...fiber.Handler) *OperationBuilder

Get adds a GET operation.

func (*Soda) Group 

func (s *Soda) Group(prefix string, handlers ...fiber.Handler) *Group

Group creates a new sub-group with optional prefix and middleware.

func (*Soda) Head added in v1.5.0 

func (s *Soda) Head(path string, handlers ...fiber.Handler) *OperationBuilder

Head adds a HEAD operation.

func (*Soda) OpenAPI 

func (s *Soda) OpenAPI() *spec.OpenAPI

OpenAPI returns the OpenAPI spec.

func (*Soda) Operation 

func (s *Soda) Operation(path, method string, handlers ...fiber.Handler) *OperationBuilder

Operation adds an operation.

func (*Soda) Options added in v1.5.0 

func (s *Soda) Options(path string, handlers ...fiber.Handler) *OperationBuilder

Options adds an OPTIONS operation.

func (*Soda) Patch 

func (s *Soda) Patch(path string, handlers ...fiber.Handler) *OperationBuilder

Patch adds a PATCH operation.

func (*Soda) Post 

func (s *Soda) Post(path string, handlers ...fiber.Handler) *OperationBuilder

Post adds a POST operation.

func (*Soda) Put 

func (s *Soda) Put(path string, handlers ...fiber.Handler) *OperationBuilder

Put adds a PUT operation.

func (*Soda) Trace added in v1.5.0 

func (s *Soda) Trace(path string, handlers ...fiber.Handler) *OperationBuilder

Trace adds a TRACE operation.

type UIRender 

type UIRender interface {
	Render(spec *spec.OpenAPI) 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.