README
¶
Gin Middleware
⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.
Middleware for the Gin web server for use with oapi-codegen/oapi-codegen.
Validated request body
The middleware enables kin-openapi's openapi3filter.Options.KeepValidatedValue by default. After a request body passes validation, c.Request.Body stays readable (with the original bytes, unless kin-openapi rewrote it to apply schema defaults) and additionally implements interface{ ValidatedValue() any }, returning the decoded value that was validated. oapi-codegen strict servers that support it can bind that value instead of decoding the body a second time, so the handler sees exactly what was validated (for example, encoding/json's case-insensitive member matching can no longer make a request validate as one value but bind as another).
To opt out, for instance to limit memory retention for very large request bodies, set Options.DiscardValidatedValue = true. This setting overrides Options.Options.KeepValidatedValue.
Any middleware placed after the validator that replaces c.Request.Body (decompression, size limiting, logging wrappers and the like) hides the validated value from handlers. Register such middleware before the validator.
Licensed under the Apache-2.0.
Documentation
¶
Index ¶
- Constants
- func GetGinContext(c context.Context) *gin.Context
- func GetUserData(c context.Context) interface{}
- func OapiRequestValidator(swagger *openapi3.T) gin.HandlerFunc
- func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) gin.HandlerFunc
- func OapiValidatorFromYamlFile(path string) (gin.HandlerFunc, error)
- func ValidateRequestFromContext(c *gin.Context, router routers.Router, options *Options) error
- type ErrorHandler
- type MultiErrorHandler
- type Options
Constants ¶
const ( GinContextKey = "oapi-codegen/gin-context" UserDataKey = "oapi-codegen/user-data" )
Variables ¶
This section is empty.
Functions ¶
func GetGinContext ¶
GetGinContext gets the gin context from within requests. It returns nil if not found or wrong type.
func GetUserData ¶
func OapiRequestValidator ¶
func OapiRequestValidator(swagger *openapi3.T) gin.HandlerFunc
OapiRequestValidator is an gin middleware function which validates incoming HTTP requests to make sure that they conform to the given OAPI 3.0 specification. When OAPI validation fails on the request, we return an HTTP/400 with error message
func OapiRequestValidatorWithOptions ¶
func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) gin.HandlerFunc
OapiRequestValidatorWithOptions creates a validator from a swagger object, with validation options
func OapiValidatorFromYamlFile ¶
func OapiValidatorFromYamlFile(path string) (gin.HandlerFunc, error)
OapiValidatorFromYamlFile creates a validator middleware from a YAML file path
Types ¶
type ErrorHandler ¶
ErrorHandler is called when there is an error in validation
type MultiErrorHandler ¶
type MultiErrorHandler func(openapi3.MultiError) error
MultiErrorHandler is called when oapi returns a MultiError type
type Options ¶
type Options struct {
ErrorHandler ErrorHandler
Options openapi3filter.Options
ParamDecoder openapi3filter.ContentParameterDecoder
UserData interface{}
MultiErrorHandler MultiErrorHandler
// SilenceServersWarning allows silencing a warning for https://github.com/deepmap/oapi-codegen/issues/882 that reports when an OpenAPI spec has `spec.Servers != nil`
SilenceServersWarning bool
// DiscardValidatedValue turns off openapi3filter.Options.KeepValidatedValue,
// which this middleware enables by default. With it enabled, the request body
// seen by handlers exposes the value that was validated through a
// ValidatedValue() method, so a handler (for example an oapi-codegen strict
// server) can bind that value instead of decoding the body a second time.
// Set this to drop the decoded value after validation, for instance to limit
// memory retention for very large request bodies.
//
// Options.Options.KeepValidatedValue is overridden by this setting.
DiscardValidatedValue bool
}
Options to customize request validation. These are passed through to openapi3filter.
Source Files