fizz

package module
v0.23.4 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2024 License: MIT Imports: 12 Imported by: 0

README

Fizz

Gin Fizz

This repository is a fork of wl2L/fizz which contain additional capabilities.

It's also based on my Tonic fork which contain several improvements.

README

Fizz is a wrapper for Gin based on gadgeto/tonic.

It generates wrapping gin-compatible handlers that do all the repetitive work and wrap the call to your handlers. It can also generates an almost complete OpenAPI 3 specification of your API.


Getting started

To create a Fizz instance, you can pass an existing Gin engine to fizz.NewFromEngine, or use fizz.New that will use a new default Gin engine.

engine := gin.Default()
engine.Use(...) // register global middlewares

f := fizz.NewFromEngine(engine)

A Fizz instance implements the http.HandlerFunc interface, which means it can be used as the base handler of your HTTP server.

srv := &http.Server{
   Addr:    ":4242",
   Handler: f,
}
srv.ListenAndServe()

Handlers

Fizz abstracts the GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD and TRACE methods of a Gin engine. These functions accept a variadic list of handlers as the last parameter, but since Fizz relies on tonic to retrieve the informations required to generate the OpenAPI specification of the operation, only one of the handlers registered MUST be wrapped with Tonic.

In the following example, the BarHandler is a simple middleware that will be executed before the FooHandler, but the generator will use the input/output type of the FooHandler to generate the specification of the operation.

func BarHandler(c *gin.Context) { ... }
func FooHandler(*gin.Context, *Foo) (*Bar, error) { ... }

fizz := fizz.New()
fizz.GET("/foo/bar", nil, BarHandler, tonic.Handler(FooHandler, 200))

However, registering only standard handlers that follow the gin.HandlerFunc signature is accepted, but the OpenAPI generator will ignore the operation and it won't appear in the specification.

Operation informations

To enrich an operation, you can pass a list of optional OperationOption functions as the second parameters of the GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD methods.

// Set the default response description.
// A default status text will be created from the code if it is omitted.
fizz.StatusDescription(desc string)

// Set the summary of the operation.
fizz.Summary(summary string)
fizz.Summaryf(format string, a ...interface{})

// Set the description of the operation.
fizz.Description(desc string)
fizz.Descriptionf(format string, a ...interface{})

// Override the ID of the operation.
// Must be a unique string used to identify the operation among
// all operations described in the API.
fizz.ID(id string)

// Mark the operation as deprecated.
fizz.Deprecated(deprecated bool)

// Add an additional response to the operation.
// The example argument will populate a single example in the response schema.
// For populating multiple examples, use fizz.ResponseWithExamples.
// Notice that example and examples fields are mutually exclusive.
// model, header, and example may be `nil`.
fizz.Response(statusCode, desc string, model interface{}, headers []*ResponseHeader, example interface{})

// ResponseWithExamples is a variant of Response that supports providing multiple examples.
// Examples argument will populate multiple examples in the response schema.
// For populating a single example, use fizz.Response.
// Notice that example and examples fields are mutually exclusive.
// model, header, and examples may be `nil`.
fizz.ResponseWithExamples(statusCode, desc string, model interface{}, headers []*ResponseHeader, examples map[string]interface{})

// Add an additional header to the default response.
// Model can be of any type, and may also be `nil`,
// in which case the string type will be used as default.
fizz.Header(name, desc string, model interface{})

// Override the binding model of the operation.
fizz.InputModel(model interface{})

// Overrides the top-level security requirement of an operation.
// Note that this function can be used more than once to add several requirements.
fizz.Security(security *openapi.SecurityRequirement)

// Add an empty security requirement to this operation to make other security requirements optional.
fizz.WithOptionalSecurity()

// Remove any top-level security requirements for this operation.
fizz.WithoutSecurity()

// Add a Code Sample to the operation.
fizz.XCodeSample(codeSample *XCodeSample)

// Mark the operation as internal. The x-internal flag is interpreted by third-party tools and it only impacts the visual documentation rendering.
fizz.XInternal()

NOTES:

  • fizz.InputModel allows to override the operation input regardless of how the handler implementation really binds the request parameters. It is the developer responsibility to ensure that the binding matches the OpenAPI specification.
  • The first argument of the fizz.Reponse method which represents an HTTP status code is of type string because the spec accept the value default. See the Responses Object documentation for more informations.

To help you declare additional headers, predefined variables for Go primitives types that you can use as the third argument of the fizz.Header method are available:

var (
   Integer  int32
   Long     int64
   Float    float32
   Double   float64
   String   string
   Byte     []byte
   Binary   []byte
   Boolean  bool
   DateTime time.Time
)

Groups

Exactly like you would do with Gin, you can create a group of routes using the method Group. Unlike Gin own method, Fizz's one takes two other optional arguments, name and description. These parameters will be used to create a tag in the OpenAPI specification that will be applied to all the routes added to the group.

grp := f.Group("/subpath", "MyGroup", "Group description", middlewares...)

If the name parameter is empty, the tag won't be created and it won't be used.

Subgroups of subgroups can be created to an infinite depth, according yo your needs.

foo := f.Group("/foo", "Foo", "Foo group")

// all routes registered on group bar will have
// a relative path starting with /foo/bar
bar := f.Group("/bar", "Bar", "Bar group")

// /foo/bar/{barID}
bar.GET("/:barID", nil, tonic.Handler(MyBarHandler, 200))

The Use method can be used with groups to register middlewares after their creation.

grp.Use(middleware1, middleware2, ...)

Tonic

The subpackage tonic handles path/query/header/body parameters binding in a single consolidated input object which allows you to remove all the boilerplate code that retrieves and tests the presence of various parameters. The OpenAPI generator make use of the input/output types informations of a tonic-wrapped handler reported by tonic to document the operation in the specification.

The handlers wrapped with tonic must follow the following signature.

func(*gin.Context, [input object ptr]) ([output object], error)

Input and output objects are both optional, as such, the minimal accepted signature is:

func(*gin.Context) error

To wrap a handler with tonic, use the tonic.Handler method. It takes a function that follow the above signature and a default status code and return a gin.HandlerFunc function that can be used when you register a route with Fizz of Gin.

Output objects can be of any type, and will be marshalled to the desired media type. Note that the input object MUST always be a pointer to a struct, or the tonic wrapping will panic at runtime.

If you use closures as handlers, please note that they will all have the same name, and the generator will return an error. To overcome this problem, you have to explicitely set the ID of an operation when you register the handler.

func MyHandler() gin.HandlerFunc {
   return tonic.Handler(func(c *gin.Context) error {}, 200)
}

fizz.GET("/foo", []fizz.OperationOption{
   fizz.ID("MyOperationID")
}, MyHandler())

Location tags

tonic uses three struct tags to recognize the parameters it should bind to the input object of your tonic-wrapped handlers:

  • path: bind from the request path
  • query: bind from the request query string
  • header: bind from the request headers

The fields that doesn't use one of these tags will be considered as part of the request body.

The value of each struct tag represents the name of the field in each location, with options.

type MyHandlerParams struct {
   ID  int64     `path:"id"`
   Foo string    `query:"foo"`
   Bar time.Time `header:"x-foo-bar"`
}

tonic will automatically convert the value extracted from the location described by the tag to the appropriate type before binding.

NOTE: A path parameter is always required and will appear required in the spec regardless of the validate tag content.

Additional tags

You can use additional tags. Some will be interpreted by tonic, others will be exclusively used to enrich the OpenAPI specification.

name description
default tonic will bind this value if none was passed with the request. This should not be used if a field is also required. Read the documentation (section Common Mistakes) for more informations about this behaviour.
description Add a description of the field in the spec.
deprecated Indicates if the field is deprecated. Accepted values are 1, t, T, TRUE, true, True, 0, f, F, FALSE. Invalid value are considered to be false.
enum A coma separated list of acceptable values for the parameter.
example An example value to be used in OpenAPI specification. See section below for the demonstration on how to provide example for custom types.
format Override the format of the field in the specification. Read the documentation for more informations.
validate Field validation rules. Read the documentation for more informations.
explode Specifies whether arrays should generate separate parameters for each array item or object property (limited to query parameters with form style). Accepted values are 1, t, T, TRUE, true, True, 0, f, F, FALSE. Invalid value are considered to be false.

JSON/XML

The JSON/XML encoders usually omit a field that has the tag "-". This behaviour is reproduced by the OpenAPI generator ; a field with this tag won't appear in the properties of the schema.

In the following example, the field Input is used only for binding request body parameters and won't appear in the output encoding while Output will be marshaled but will not be used for parameters binding.

type Model struct {
	Input  string `json:"-"`
	Output string `json:"output" binding:"-"`
}

Request body

If you want to make a request body field mandatory, you can use the tag validate:"required". The validator used by tonic will ensure that the field is present. To be able to make a difference between a missing value and the zero value of a type, use a pointer.

To explicitly ignore a parameter from the request body, use the tag binding:"-".

Note that the OpenAPI generator will ignore request body parameters for the routes with a method that is one of GET, DELETE or HEAD.

GET, DELETE and HEAD are no longer allowed to have request body because it does not have defined semantics as per RFC 7231. source

Schema validation

The OpenAPI generator recognize some tags of the go-playground/validator.v8 package and translate those to the properties of the schema that are taken from the JSON Schema definition.

The supported tags are: len, max, min, eq, gt, gte, lt, lte.

Based on the type of the field that carry the tag, the fields maximum, minimum, minLength, maxLength, minItems, maxItems, minProperties and maxProperties of its JSON Schema will be filled accordingly.

OpenAPI specification

To serve the generated OpenAPI specification in either JSON or YAML format, use the handler returned by the fizz.OpenAPI method.

To enrich the specification, you can provide additional informations. Head to the OpenAPI 3 spec for more informations about the API informations that you can specify, or take a look at the type openapi.Info in the file openapi/spec.go.

f := fizz.New()
infos := &openapi.Info{
   Title:       "Fruits Market",
   Description: `This is a sample Fruits market server.`,
   Version:     "1.0.0",
}
f.GET("/openapi.json", nil, f.OpenAPI(infos, "json"))

NOTE: The generator will never panic. However, it is strongly recommended to call fizz.Errors to retrieve and handle the errors that may have occured during the generation of the specification before starting your API.

Servers information

If the OpenAPI specification refers to an API that is not hosted on the same domain, or using a path prefix not included in the spec, you will have to declare server information. This can be achieved using the f.Generator().SetServers method.

f := fizz.New()
f.Generator().SetServers([]*openapi.Server{
   {
      Description: "Fruits Market - production",
      URL:         "https://example.org/api/1.0",
   },
})
Security schemes

If your API requires authentication, you have to declare the security schemes that can be used by the operations. This can be achieved using the f.Generator().SetSecuritySchemes method.

f := fizz.New()
f.Generator().SetSecuritySchemes(map[string]*openapi.SecuritySchemeOrRef{
   "apiToken": {
      SecurityScheme: &openapi.SecurityScheme{
         Type: "apiKey",
         In:   "header",
         Name: "x-api-token",
      },
   },
})

Once defined, the security schemes will be available for all operations. You can override them on an per-operation basis using the fizz.Security() function.

fizz.Security(&openapi.SecurityRequirement{
   "apiToken": []string{},
})
Components

The output types of your handlers are registered as components within the generated specification. By default, the name used for each component is composed of the package and type name concatenated using CamelCase style, and does not contain the full import path. As such, please ensure that you don't use the same type name in two eponym package in your application.

The names of the components can be customized in two different ways.

Global override

Override the name of a type globally before registering your handlers. This has the highest precedence.

f := fizz.New()
f.Generator().OverrideTypeName(reflect.TypeOf(T{}), "OverridedName")
Interface

Implements the openapi.Typer interface on your types.

func (*T) TypeName() string { return "OverridedName" }

WARNING: You MUST not rely on the method receiver to return the name, because the method will be called on a new instance created by the generator with the reflect package.

Custom schemas

The spec generator creates OpenAPI schemas for your types based on their reflection kind. If you want to control the output schema of a type manually, you can implement the DataType interface for this type.

For example, given a UUID version 4 type, declared as a struct, that should appear as a string with a custom format.

type UUIDv4 struct { ... }

func (*UUIDv4) Format() string { return "uuid" }
func (*UUIDv4) Type() string { return "string" }

The schema of the type will look like the following instead of describing all the fields of the struct.

{
   "type": "string",
   "format": "uuid"
}

If you want to override the nullable property of a type, you can implement the Nullable interface for this type.

For example, if sql.NullString is not referenced by a pointer in your model but you still want it to be "nullable":

type NullString sql.NullString

func (NullString) Nullable() bool { return true }

WARNING: You MUST not rely on the method receivers to return the type and format, because these methods will be called on a new instance created by the generator with the reflect package.

You can also override manually the type and format using OverrideDataType(). This has the highest precedence.

fizz.Generator().OverrideDataType(reflect.TypeOf(&UUIDv4{}), "string", "uuid")
Native and imported types support

Fizz supports some native and imported types. A schema with a proper type and format will be generated automatically, removing the need for creating your own custom schema.

Note that, according to the doc, the inherent version of the address is a semantic property, and thus cannot be determined by Fizz. Therefore, the format returned is simply ip. If you want to specify the version, you can use the tags format:"ipv4" or format:"ipv6".

Markdown

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns. source

To help you write markdown descriptions in Go, a simple builder is available in the sub-package markdown. This is quite handy to avoid conflicts with backticks that are both used in Go for litteral multi-lines strings and code blocks in markdown.

Providing Examples for Custom Types

To be able to provide examples for custom types, they must implement the json.Marshaler and/or yaml.Marshaler and the following interface:

type Exampler interface {
       ParseExample(v string) (interface{}, error)
}

If the custom type implements the interface, Fizz will pass the value from the example tag to the ParseExample method and use the return value as the example in the OpenAPI specification.

Known limitations

  • Since OpenAPI is based on the JSON Schema specification itself, objects (Go maps) with keys that are not of type string are not supported and will be ignored during the generation of the specification.
  • Recursive embedding of the same type is not supported, at any level of recursion. The generator will warn and skip the offending fields. 
    type A struct {
   Foo int
   *A   // ko, embedded and same type as parent
   A *A // ok, not embedded
   *B   // ok, different type
}

type B struct {
   Bar string
   *A // ko, type B is embedded in type A
   *C // ok, type C does not contains an embedded field of type A
}

type C struct {
   Baz bool
}

Examples

A simple runnable API is available in examples/market.

go build
./market
# Retrieve the specification marshaled in JSON.
curl -i http://localhost:4242/openapi.json

Credits

Fizz is based on gin-gonic/gin and use gadgeto/tonic. ❤

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	Integer  int32
	Long     int64
	Float    float32
	Double   float64
	String   string
	Byte     []byte
	Binary   []byte
	Boolean  bool
	DateTime time.Time
)

Primitive type helpers.

Functions

func Deprecated 

func Deprecated(deprecated bool) func(*openapi.OperationInfo)

Deprecated marks the operation as deprecated.

func Description 

func Description(desc string) func(*openapi.OperationInfo)

Description adds a description to an operation.

func Descriptionf 

func Descriptionf(format string, a ...interface{}) func(*openapi.OperationInfo)

Descriptionf adds a description to an operation according to a format specifier. 

func Header(name, desc string, model interface{}) func(*openapi.OperationInfo)

Header adds a header to the operation.

func ID 

func ID(id string) func(*openapi.OperationInfo)

ID overrides the operation ID.

func InputModel 

func InputModel(model interface{}) func(*openapi.OperationInfo)

InputModel overrides the binding model of the operation.

func OperationFromContext 

func OperationFromContext(ctx context.Context) (*openapi.Operation, error)

OperationFromContext returns the OpenAPI operation from the given Gin context or an error if none is found.

func Response 

func Response(statusCode, desc string, model interface{}, headers []*openapi.ResponseHeader, example interface{}) func(*openapi.OperationInfo)

Response adds an additional response to the operation.

func ResponseWithExamples 

func ResponseWithExamples(statusCode, desc string, model interface{}, headers []*openapi.ResponseHeader, examples map[string]interface{}) func(*openapi.OperationInfo)

ResponseWithExamples is a variant of Response that accept many examples.

func Security 

func Security(security *openapi.SecurityRequirement) func(*openapi.OperationInfo)

Overrides top-level security requirement for this operation. Note that this function can be used more than once to add several requirements.

func StatusDescription 

func StatusDescription(desc string) func(*openapi.OperationInfo)

StatusDescription sets the default status description of the operation.

func Summary 

func Summary(summary string) func(*openapi.OperationInfo)

Summary adds a summary to an operation.

func Summaryf 

func Summaryf(format string, a ...interface{}) func(*openapi.OperationInfo)

Summaryf adds a summary to an operation according to a format specifier.

func WithOptionalSecurity 

func WithOptionalSecurity() func(*openapi.OperationInfo)

Add an empty security requirement to this operation to make other security requirements optional.

func WithoutSecurity 

func WithoutSecurity() func(*openapi.OperationInfo)

Remove any top-level security requirements for this operation.

func XCodeSample 

func XCodeSample(cs *openapi.XCodeSample) func(*openapi.OperationInfo)

XCodeSample adds a code sample to the operation.

func XInternal 

func XInternal() func(*openapi.OperationInfo)

XInternal marks the operation as internal.

Types

type Fizz 

type Fizz struct {
	*RouterGroup
	// contains filtered or unexported fields
}

Fizz is an abstraction of a Gin engine that wraps the routes handlers with Tonic and generates an OpenAPI 3.0 specification from it.

func New 

func New() *Fizz

New creates a new Fizz wrapper for a default Gin engine.

func NewFromEngine 

func NewFromEngine(e *gin.Engine) *Fizz

NewFromEngine creates a new Fizz wrapper from an existing Gin engine.

func (*Fizz) Engine 

func (f *Fizz) Engine() *gin.Engine

Engine returns the underlying Gin engine.

func (*Fizz) Errors 

func (f *Fizz) Errors() []error

Errors returns the errors that may have occurred during the spec generation.

func (*Fizz) Generator 

func (f *Fizz) Generator() *openapi.Generator

Generator returns the underlying OpenAPI generator.

func (*Fizz) GinRouterGroup 

func (f *Fizz) GinRouterGroup() *gin.RouterGroup

GinRouterGroup returns the underlying Gin router group.

func (*Fizz) OpenAPI 

func (f *Fizz) OpenAPI(info *openapi.Info, ct string) gin.HandlerFunc

OpenAPI returns a Gin HandlerFunc that serves the marshalled OpenAPI specification of the API.

func (*Fizz) ServeHTTP 

func (f *Fizz) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.HandlerFunc for Fizz.

type OperationOption 

type OperationOption func(*openapi.OperationInfo)

OperationOption represents an option-pattern function used to add informations to an operation.

type RouterGroup 

type RouterGroup struct {
	Name        string
	Description string
	// contains filtered or unexported fields
}

RouterGroup is an abstraction of a Gin router group.

func (*RouterGroup) DELETE 

func (g *RouterGroup) DELETE(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

DELETE is a shortcut to register a new handler with the DELETE method.

func (*RouterGroup) GET 

func (g *RouterGroup) GET(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

GET is a shortcut to register a new handler with the GET method.

func (*RouterGroup) GinRouterGroup 

func (g *RouterGroup) GinRouterGroup() *gin.RouterGroup

GinRouterGroup returns the underlying Gin router group.

func (*RouterGroup) Group 

func (g *RouterGroup) Group(path, name, description string, handlers ...gin.HandlerFunc) *RouterGroup

Group creates a new group of routes.

func (*RouterGroup) HEAD 

func (g *RouterGroup) HEAD(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

HEAD is a shortcut to register a new handler with the HEAD method.

func (*RouterGroup) Handle 

func (g *RouterGroup) Handle(path, method string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

Handle registers a new request handler that is wrapped with Tonic and documented in the OpenAPI specification.

func (*RouterGroup) OPTIONS 

func (g *RouterGroup) OPTIONS(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

OPTIONS is a shortcut to register a new handler with the OPTIONS method.

func (*RouterGroup) PATCH 

func (g *RouterGroup) PATCH(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

PATCH is a shortcut to register a new handler with the PATCH method.

func (*RouterGroup) POST 

func (g *RouterGroup) POST(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

POST is a shortcut to register a new handler with the POST method.

func (*RouterGroup) PUT 

func (g *RouterGroup) PUT(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

PUT is a shortcut to register a new handler with the PUT method.

func (*RouterGroup) TRACE 

func (g *RouterGroup) TRACE(path string, infos []OperationOption, handlers ...gin.HandlerFunc) *RouterGroup

TRACE is a shortcut to register a new handler with the TRACE method.

func (*RouterGroup) Use 

func (g *RouterGroup) Use(handlers ...gin.HandlerFunc)

Use adds middleware to the group.

Source Files

View all Source files

Directories

Path Synopsis
examples
market

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.