Documentation

Overview

    Package openapi3filter validates that requests and inputs request an OpenAPI 3 specification file.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var DefaultOptions = &Options{}
    View Source
    var (
    	ErrAuthenticationServiceMissing = errors.New("Request validator doesn't have an authentication service defined")
    )
    View Source
    var ErrInvalidRequired = errors.New("must have a value")

      ErrInvalidRequired is an error that happens when a required value of a parameter or request's body is not defined.

      View Source
      var JSONPrefixes = []string{
      	")]}',\n",
      }

      Functions

      func DefaultErrorEncoder

      func DefaultErrorEncoder(_ context.Context, err error, w http.ResponseWriter)

        DefaultErrorEncoder writes the error to the ResponseWriter, by default a content type of text/plain, a body of the plain text of the error, and a status code of 500. If the error implements Headerer, the provided headers will be applied to the response. If the error implements json.Marshaler, and the marshaling succeeds, a content type of application/json and the JSON encoded form of the error will be used. If the error implements StatusCoder, the provided StatusCode will be used instead of 500.

        func FileBodyDecoder

        func FileBodyDecoder(body io.Reader, header http.Header, schema *openapi3.SchemaRef, encFn EncodingFn) (interface{}, error)

          FileBodyDecoder is a body decoder that decodes a file body to a string.

          func NoopAuthenticationFunc

          func NoopAuthenticationFunc(context.Context, *AuthenticationInput) error

          func RegisterBodyDecoder

          func RegisterBodyDecoder(contentType string, decoder BodyDecoder)

            RegisterBodyDecoder registers a request body's decoder for a content type.

            If a decoder for the specified content type already exists, the function replaces it with the specified decoder.

            func TrimJSONPrefix

            func TrimJSONPrefix(data []byte) []byte

              TrimJSONPrefix trims one of the possible prefixes

              func UnregisterBodyDecoder

              func UnregisterBodyDecoder(contentType string)

                UnregisterBodyDecoder dissociates a body decoder from a content type.

                Decoding this content type will result in an error.

                func ValidateParameter

                func ValidateParameter(c context.Context, input *RequestValidationInput, parameter *openapi3.Parameter) error

                  ValidateParameter validates a parameter's value by JSON schema. The function returns RequestError with a ParseError cause when unable to parse a value. The function returns RequestError with ErrInvalidRequired cause when a value of a required parameter is not defined. The function returns RequestError with a openapi3.SchemaError cause when a value is invalid by JSON schema.

                  func ValidateRequest

                  func ValidateRequest(c context.Context, input *RequestValidationInput) error

                    ValidateRequest is used to validate the given input according to previous loaded OpenAPIv3 spec. If the input does not match the OpenAPIv3 spec, a non-nil error will be returned.

                    Note: One can tune the behavior of uniqueItems: true verification by registering a custom function with openapi3.RegisterArrayUniqueItemsChecker

                    func ValidateRequestBody

                    func ValidateRequestBody(c context.Context, input *RequestValidationInput, requestBody *openapi3.RequestBody) error

                      ValidateRequestBody validates data of a request's body.

                      The function returns RequestError with ErrInvalidRequired cause when a value is required but not defined. The function returns RequestError with a openapi3.SchemaError cause when a value is invalid by JSON schema.

                      func ValidateResponse

                      func ValidateResponse(c context.Context, input *ResponseValidationInput) error

                        ValidateResponse is used to validate the given input according to previous loaded OpenAPIv3 spec. If the input does not match the OpenAPIv3 spec, a non-nil error will be returned.

                        Note: One can tune the behavior of uniqueItems: true verification by registering a custom function with openapi3.RegisterArrayUniqueItemsChecker

                        func ValidateSecurityRequirements

                        func ValidateSecurityRequirements(c context.Context, input *RequestValidationInput, srs openapi3.SecurityRequirements) error

                          ValidateSecurityRequirements goes through multiple OpenAPI 3 security requirements in order and returns nil on the first valid requirement. If no requirement is met, errors are returned in order.

                          Types

                          type AuthenticationFunc

                          type AuthenticationFunc func(context.Context, *AuthenticationInput) error

                          type AuthenticationInput

                          type AuthenticationInput struct {
                          	RequestValidationInput *RequestValidationInput
                          	SecuritySchemeName     string
                          	SecurityScheme         *openapi3.SecurityScheme
                          	Scopes                 []string
                          }

                          func (*AuthenticationInput) NewError

                          func (input *AuthenticationInput) NewError(err error) error

                          type BodyDecoder

                          type BodyDecoder func(io.Reader, http.Header, *openapi3.SchemaRef, EncodingFn) (interface{}, error)

                            BodyDecoder is an interface to decode a body of a request or response. An implementation must return a value that is a primitive, []interface{}, or map[string]interface{}.

                            type ContentParameterDecoder

                            type ContentParameterDecoder func(param *openapi3.Parameter, values []string) (interface{}, *openapi3.Schema, error)

                              A ContentParameterDecoder takes a parameter definition from the swagger spec, and the value which we received for it. It is expected to return the value unmarshaled into an interface which can be traversed for validation, it should also return the schema to be used for validating the object, since there can be more than one in the content spec.

                              If a query parameter appears multiple times, values[] will have more than one value, but for all other parameter types it should have just one.

                              type EncodingFn

                              type EncodingFn func(partName string) *openapi3.Encoding

                                EncodingFn is a function that returns an encoding of a request body's part.

                                type ErrorEncoder

                                type ErrorEncoder func(ctx context.Context, err error, w http.ResponseWriter)

                                  ErrorEncoder is responsible for encoding an error to the ResponseWriter. Users are encouraged to use custom ErrorEncoders to encode HTTP errors to their clients, and will likely want to pass and check for their own error types. See the example shipping/handling service.

                                  type Headerer

                                  type Headerer interface {
                                  	Headers() http.Header
                                  }

                                    Headerer is checked by DefaultErrorEncoder. If an error value implements Headerer, the provided headers will be applied to the response writer, after the Content-Type is set.

                                    type Options

                                    type Options struct {
                                    	ExcludeRequestBody    bool
                                    	ExcludeResponseBody   bool
                                    	IncludeResponseStatus bool
                                    	MultiError            bool
                                    	AuthenticationFunc    func(c context.Context, input *AuthenticationInput) error
                                    }

                                    type ParseError

                                    type ParseError struct {
                                    	Kind   ParseErrorKind
                                    	Value  interface{}
                                    	Reason string
                                    	Cause  error
                                    	// contains filtered or unexported fields
                                    }

                                      ParseError describes errors which happens while parse operation's parameters, requestBody, or response.

                                      func (*ParseError) Error

                                      func (e *ParseError) Error() string

                                      func (*ParseError) Path

                                      func (e *ParseError) Path() []interface{}

                                        Path returns a path to the root cause.

                                        func (*ParseError) RootCause

                                        func (e *ParseError) RootCause() error

                                          RootCause returns a root cause of ParseError.

                                          type ParseErrorKind

                                          type ParseErrorKind int

                                            ParseErrorKind describes a kind of ParseError. The type simplifies comparison of errors.

                                            const (
                                            	// KindOther describes an untyped parsing error.
                                            	KindOther ParseErrorKind = iota
                                            	// KindUnsupportedFormat describes an error that happens when a value has an unsupported format.
                                            	KindUnsupportedFormat
                                            	// KindInvalidFormat describes an error that happens when a value does not conform a format
                                            	// that is required by a serialization method.
                                            	KindInvalidFormat
                                            )

                                            type RequestError

                                            type RequestError struct {
                                            	Input       *RequestValidationInput
                                            	Parameter   *openapi3.Parameter
                                            	RequestBody *openapi3.RequestBody
                                            	Status      int
                                            	Reason      string
                                            	Err         error
                                            }

                                            func (*RequestError) Error

                                            func (err *RequestError) Error() string

                                            func (*RequestError) HTTPStatus

                                            func (err *RequestError) HTTPStatus() int

                                            type RequestValidationInput

                                            type RequestValidationInput struct {
                                            	Request      *http.Request
                                            	PathParams   map[string]string
                                            	QueryParams  url.Values
                                            	Route        *Route
                                            	Options      *Options
                                            	ParamDecoder ContentParameterDecoder
                                            }

                                            func (*RequestValidationInput) GetQueryParams

                                            func (input *RequestValidationInput) GetQueryParams() url.Values

                                            type ResponseError

                                            type ResponseError struct {
                                            	Input  *ResponseValidationInput
                                            	Reason string
                                            	Err    error
                                            }

                                            func (*ResponseError) Error

                                            func (err *ResponseError) Error() string

                                            type ResponseValidationInput

                                            type ResponseValidationInput struct {
                                            	RequestValidationInput *RequestValidationInput
                                            	Status                 int
                                            	Header                 http.Header
                                            	Body                   io.ReadCloser
                                            	Options                *Options
                                            }

                                            func (*ResponseValidationInput) SetBodyBytes

                                            func (input *ResponseValidationInput) SetBodyBytes(value []byte) *ResponseValidationInput

                                            type Route

                                            type Route struct {
                                            	Swagger   *openapi3.Swagger
                                            	Server    *openapi3.Server
                                            	Path      string
                                            	PathItem  *openapi3.PathItem
                                            	Method    string
                                            	Operation *openapi3.Operation
                                            
                                            	// For developers who want use the router for handling too
                                            	Handler http.Handler
                                            }

                                            type RouteError

                                            type RouteError struct {
                                            	Route  Route
                                            	Reason string
                                            }

                                            func (*RouteError) Error

                                            func (err *RouteError) Error() string

                                            type Router

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

                                              Router maps a HTTP request to an OpenAPI operation.

                                              func NewRouter

                                              func NewRouter() *Router

                                                NewRouter creates a new router.

                                                If the given Swagger has servers, router will use them. All operations of the Swagger will be added to the router.

                                                func (*Router) AddRoute

                                                func (router *Router) AddRoute(route *Route) error

                                                  AddRoute adds a route in the router.

                                                  func (*Router) AddSwagger

                                                  func (router *Router) AddSwagger(swagger *openapi3.Swagger) error

                                                    AddSwagger adds all operations in the OpenAPI specification.

                                                    func (*Router) AddSwaggerFromFile

                                                    func (router *Router) AddSwaggerFromFile(path string) error

                                                      AddSwaggerFromFile loads the Swagger file and adds it using AddSwagger.

                                                      func (*Router) FindRoute

                                                      func (router *Router) FindRoute(method string, url *url.URL) (*Route, map[string]string, error)

                                                      func (*Router) WithSwagger

                                                      func (router *Router) WithSwagger(swagger *openapi3.Swagger) *Router

                                                        WithSwagger adds all operations in the OpenAPI specification. Panics on any error.

                                                        func (*Router) WithSwaggerFromFile

                                                        func (router *Router) WithSwaggerFromFile(path string) *Router

                                                          WithSwaggerFromFile loads the Swagger file and adds it using WithSwagger. Panics on any error.

                                                          type Routers

                                                          type Routers []*Router

                                                            Routers maps a HTTP request to a Router.

                                                            func (Routers) FindRoute

                                                            func (routers Routers) FindRoute(method string, url *url.URL) (*Router, *Route, map[string]string, error)

                                                            type SecurityRequirementsError

                                                            type SecurityRequirementsError struct {
                                                            	SecurityRequirements openapi3.SecurityRequirements
                                                            	Errors               []error
                                                            }

                                                            func (*SecurityRequirementsError) Error

                                                            func (err *SecurityRequirementsError) Error() string

                                                            type StatusCoder

                                                            type StatusCoder interface {
                                                            	StatusCode() int
                                                            }

                                                              StatusCoder is checked by DefaultErrorEncoder. If an error value implements StatusCoder, the StatusCode will be used when encoding the error. By default, StatusInternalServerError (500) is used.

                                                              type ValidationError

                                                              type ValidationError struct {
                                                              	// A unique identifier for this particular occurrence of the problem.
                                                              	Id string `json:"id,omitempty"`
                                                              	// The HTTP status code applicable to this problem.
                                                              	Status int `json:"status,omitempty"`
                                                              	// An application-specific error code, expressed as a string value.
                                                              	Code string `json:"code,omitempty"`
                                                              	// A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
                                                              	Title string `json:"title,omitempty"`
                                                              	// A human-readable explanation specific to this occurrence of the problem.
                                                              	Detail string `json:"detail,omitempty"`
                                                              	// An object containing references to the source of the error
                                                              	Source *ValidationErrorSource `json:"source,omitempty"`
                                                              }

                                                                ValidationError struct provides granular error information useful for communicating issues back to end user and developer. Based on https://jsonapi.org/format/#error-objects

                                                                func (*ValidationError) Error

                                                                func (e *ValidationError) Error() string

                                                                  Error implements the error interface.

                                                                  func (*ValidationError) StatusCode

                                                                  func (e *ValidationError) StatusCode() int

                                                                    StatusCode implements the StatusCoder interface for DefaultErrorEncoder

                                                                    type ValidationErrorEncoder

                                                                    type ValidationErrorEncoder struct {
                                                                    	Encoder ErrorEncoder
                                                                    }

                                                                      ValidationErrorEncoder wraps a base ErrorEncoder to handle ValidationErrors

                                                                      func (*ValidationErrorEncoder) Encode

                                                                        Encode implements the ErrorEncoder interface for encoding ValidationErrors

                                                                        type ValidationErrorSource

                                                                        type ValidationErrorSource struct {
                                                                        	// A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute].
                                                                        	Pointer string `json:"pointer,omitempty"`
                                                                        	// A string indicating which query parameter caused the error.
                                                                        	Parameter string `json:"parameter,omitempty"`
                                                                        }

                                                                          ValidationErrorSource struct

                                                                          type ValidationHandler

                                                                          type ValidationHandler struct {
                                                                          	Handler            http.Handler
                                                                          	AuthenticationFunc AuthenticationFunc
                                                                          	SwaggerFile        string
                                                                          	ErrorEncoder       ErrorEncoder
                                                                          	// contains filtered or unexported fields
                                                                          }

                                                                          func (*ValidationHandler) Load

                                                                          func (h *ValidationHandler) Load() error

                                                                          func (*ValidationHandler) Middleware

                                                                          func (h *ValidationHandler) Middleware(next http.Handler) http.Handler

                                                                            Middleware implements gorilla/mux MiddlewareFunc

                                                                            func (*ValidationHandler) ServeHTTP

                                                                            func (h *ValidationHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)