Documentation
¶
Overview ¶
Package versionware provides routing and middleware for building versioned HTTP services.
Index ¶
Examples ¶
Constants ¶
const ( // HeaderW3SecurityVersionRequested is a response header acknowledging the API // version that was requested. HeaderW3SecurityVersionRequested = "w3security-version-requested" // HeaderW3SecurityVersionServed is a response header indicating the actual API // version that was matched and served the response. HeaderW3SecurityVersionServed = "w3security-version-served" )
Variables ¶
This section is empty.
Functions ¶
func DefaultVersionError ¶
DefaultVersionError provides a basic implementation of VersionErrorHandler that uses http.Error.
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is a multiplexing http.Handler that dispatches requests based on the version query parameter according to vervet's API version matching rules.
Example ¶
h := versionware.NewHandler([]versionware.VersionHandler{{
Version: vervet.MustParseVersion("2021-10-01"),
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if _, err := w.Write([]byte("oct")); err != nil {
panic(err)
}
}),
}, {
Version: vervet.MustParseVersion("2021-11-01"),
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if _, err := w.Write([]byte("nov")); err != nil {
panic(err)
}
}),
}, {
Version: vervet.MustParseVersion("2021-09-01"),
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if _, err := w.Write([]byte("sept")); err != nil {
panic(err)
}
}),
}}...)
s := httptest.NewServer(h)
defer s.Close()
resp, err := s.Client().Get(s.URL + "?version=2021-10-31")
if err != nil {
panic(err)
}
defer resp.Body.Close()
respBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Print(string(respBody))
Output: oct
func NewHandler ¶
func NewHandler(vhs ...VersionHandler) *Handler
NewHandler returns a new Handler instance, which handles versioned requests with the matching version handler.
func (*Handler) HandleErrors ¶
func (h *Handler) HandleErrors(errFunc VersionErrorHandler)
HandleErrors changes the default error handler to the provided function. It may be used to control the format of versioning error responses.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator provides versioned OpenAPI validation middleware for HTTP requests and responses.
func NewValidator ¶
func NewValidator(config *ValidatorConfig, docs ...*openapi3.T) (*Validator, error)
NewValidator returns a new validation middleware, which validates versioned requests according to the given OpenAPI spec versions. For configuration defaults, a nil config may be used.
type ValidatorConfig ¶
type ValidatorConfig struct {
// ServerURL overrides the server URLs in the given OpenAPI specs to match
// the URL of requests reaching the backend service. If unset, requests
// must match the servers defined in OpenAPI specs.
ServerURL string
// VersionError is called on any error that occurs when trying to resolve the
// API version.
VersionError VersionErrorHandler
// Options further configure the request and response validation. See
// https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3filter#ValidatorOption
// for available options.
Options []openapi3filter.ValidatorOption
}
ValidatorConfig defines how a new Validator may be configured.
type VersionErrorHandler ¶
VersionErrorHandler defines a function which handles versioning error responses in requests.
type VersionHandler ¶
VersionHandler expresses a pairing of Version and http.Handler.
Source Files