middleware

Documentation

Overview

Package middleware provides the library with helper functions for serving swagger APIs.

Pseudo middleware handler

import (
	"net/http"

	"github.com/go-swagger/go-swagger/errors"
	"github.com/gorilla/context"
)

func newCompleteMiddleware(ctx *Context) http.Handler {
	return http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
		defer context.Clear(r)

		// use context to lookup routes
		if matched, ok := ctx.RouteInfo(r); ok {

			if len(matched.Authenticators) > 0 {
				if _, err := ctx.Authorize(r, matched); err != nil {
					ctx.Respond(rw, r, matched.Produces, matched, err)
					return
				}
			}

			bound, validation := ctx.BindAndValidate(r, matched)
			if validation != nil {
				ctx.Respond(rw, r, matched.Produces, matched, validation)
				return
			}

			result, err := matched.Handler.Handle(bound)
			if err != nil {
				ctx.Respond(rw, r, matched.Produces, matched, err)
				return
			}

			ctx.Respond(rw, r, matched.Produces, matched, result)
			return
		}

		// Not found, check if it exists in the other methods first
		if others := ctx.AllowedMethods(r); len(others) > 0 {
			ctx.Respond(rw, r, ctx.spec.RequiredProduces(), nil, errors.MethodNotAllowed(r.Method, others))
			return
		}
		ctx.Respond(rw, r, ctx.spec.RequiredProduces(), nil, errors.NotFound("path %s was not found", r.URL.Path))
	})
}

Index

• func PassthroughBuilder(handler http.Handler) http.Handler
• func Serve(spec *spec.Document, api *untyped.API) http.Handler
• func ServeWithBuilder(spec *spec.Document, api *untyped.API, builder Builder) http.Handler
• func Spec(basePath string, swsp *spec.Swagger, next http.Handler) http.Handler
• type Builder
• type Context
  • func NewContext(spec *spec.Document, api *untyped.API, routes Router) *Context
  • func NewRoutableContext(spec *spec.Document, routableAPI RoutableAPI, routes Router) *Context
  • func (c *Context) APIHandler(builder Builder) http.Handler
  • func (c *Context) AllowedMethods(request *http.Request) []string
  • func (c *Context) Authorize(request *http.Request, route *MatchedRoute) (interface{}, error)
  • func (c *Context) BasePath() string
  • func (c *Context) BindAndValidate(request *http.Request, matched *MatchedRoute) (interface{}, error)
  • func (c *Context) BindValidRequest(request *http.Request, route *MatchedRoute, binder RequestBinder) error
  • func (c *Context) ContentType(request *http.Request) (string, string, *errors.ParseError)
  • func (c *Context) LookupRoute(request *http.Request) (*MatchedRoute, bool)
  • func (c *Context) NotFound(rw http.ResponseWriter, r *http.Request)
  • func (c *Context) RequiredProduces() []string
  • func (c *Context) Respond(rw http.ResponseWriter, r *http.Request, produces []string, ...)
  • func (c *Context) ResponseFormat(r *http.Request, offers []string) string
  • func (c *Context) RouteInfo(request *http.Request) (*MatchedRoute, bool)
• type MatchedRoute
• type RequestBinder
• type Responder
  • func NotImplemented(message string) Responder
• type RoutableAPI
• type RouteParam
• type RouteParams
  • func (r RouteParams) Get(name string) string
  • func (r RouteParams) GetOK(name string) ([]string, bool, bool)
• type Router
  • func DefaultRouter(spec *spec.Document, api RoutableAPI) Router

Functions

func PassthroughBuilder

func PassthroughBuilder(handler http.Handler) http.Handler

PassthroughBuilder returns the handler, aka the builder identity function

func Serve

func Serve(spec *spec.Document, api *untyped.API) http.Handler

Serve serves the specified spec with the specified api registrations as a http.Handler

func ServeWithBuilder

func ServeWithBuilder(spec *spec.Document, api *untyped.API, builder Builder) http.Handler

ServeWithBuilder serves the specified spec with the specified api registrations as a http.Handler that is decorated by the Builder

func Spec

func Spec(basePath string, swsp *spec.Swagger, next http.Handler) http.Handler

Spec creates a middleware to serve a swagger spec. This allows for altering the spec before starting the http listener. This can be useful

Types

type Builder

type Builder func(http.Handler) http.Handler

A Builder can create middlewares

type Context

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

Context is a type safe wrapper around an untyped request context used throughout to store request context with the gorilla context module

func NewContext

func NewContext(spec *spec.Document, api *untyped.API, routes Router) *Context

NewContext creates a new context wrapper

func NewRoutableContext

func NewRoutableContext(spec *spec.Document, routableAPI RoutableAPI, routes Router) *Context

NewRoutableContext creates a new context for a routable API

func (*Context) APIHandler

func (c *Context) APIHandler(builder Builder) http.Handler

APIHandler returns a handler to serve

func (*Context) AllowedMethods

func (c *Context) AllowedMethods(request *http.Request) []string

AllowedMethods gets the allowed methods for the path of this request

func (*Context) Authorize

func (c *Context) Authorize(request *http.Request, route *MatchedRoute) (interface{}, error)

Authorize authorizes the request

func (*Context) BasePath

func (c *Context) BasePath() string

BasePath returns the base path for this API

func (*Context) BindAndValidate

func (c *Context) BindAndValidate(request *http.Request, matched *MatchedRoute) (interface{}, error)

BindAndValidate binds and validates the request

func (*Context) BindValidRequest

func (c *Context) BindValidRequest(request *http.Request, route *MatchedRoute, binder RequestBinder) error

BindValidRequest binds a params object to a request but only when the request is valid if the request is not valid an error will be returned

func (*Context) ContentType

func (c *Context) ContentType(request *http.Request) (string, string, *errors.ParseError)

ContentType gets the parsed value of a content type

func (*Context) LookupRoute

func (c *Context) LookupRoute(request *http.Request) (*MatchedRoute, bool)

LookupRoute looks a route up and returns true when it is found

func (*Context) NotFound

func (c *Context) NotFound(rw http.ResponseWriter, r *http.Request)

NotFound the default not found responder for when no route has been matched yet

func (*Context) RequiredProduces

func (c *Context) RequiredProduces() []string

RequiredProduces returns the accepted content types for responses

func (*Context) Respond

func (c *Context) Respond(rw http.ResponseWriter, r *http.Request, produces []string, route *MatchedRoute, data interface{})

Respond renders the response after doing some content negotiation

func (*Context) ResponseFormat

func (c *Context) ResponseFormat(r *http.Request, offers []string) string

ResponseFormat negotiates the response content type

func (*Context) RouteInfo

func (c *Context) RouteInfo(request *http.Request) (*MatchedRoute, bool)

RouteInfo tries to match a route for this request

type MatchedRoute

type MatchedRoute struct {
	Params   RouteParams
	Consumer httpkit.Consumer
	Producer httpkit.Producer
	// contains filtered or unexported fields
}

MatchedRoute represents the route that was matched in this request

type RequestBinder

type RequestBinder interface {
	BindRequest(*http.Request, *MatchedRoute) error
}

RequestBinder is an interface for types to implement when they want to be able to bind from a request

type Responder

type Responder interface {
	WriteResponse(http.ResponseWriter, httpkit.Producer)
}

Responder is an interface for types to implement when they want to be considered for writing HTTP responses

func NotImplemented

func NotImplemented(message string) Responder

NotImplemented the error response when the response is not implemented

type RoutableAPI

type RoutableAPI interface {
	HandlerFor(string, string) (http.Handler, bool)
	ServeErrorFor(string) func(http.ResponseWriter, *http.Request, error)
	ConsumersFor([]string) map[string]httpkit.Consumer
	ProducersFor([]string) map[string]httpkit.Producer
	AuthenticatorsFor(map[string]spec.SecurityScheme) map[string]httpkit.Authenticator
	Formats() strfmt.Registry
	DefaultProduces() string
	DefaultConsumes() string
}

RoutableAPI represents an interface for things that can serve as a provider of implementations for the swagger router

type RouteParam

type RouteParam struct {
	Name  string
	Value string
}

RouteParam is a object to capture route params in a framework agnostic way. implementations of the muxer should use these route params to communicate with the swagger framework

type RouteParams

type RouteParams []RouteParam

RouteParams the collection of route params

func (RouteParams) Get

func (r RouteParams) Get(name string) string

Get gets the value for the route param for the specified key

func (RouteParams) GetOK

func (r RouteParams) GetOK(name string) ([]string, bool, bool)

GetOK gets the value but also returns booleans to indicate if a key or value is present. This aids in validation and satisfies an interface in use there

The returned values are: data, has key, has value

type Router

type Router interface {
	Lookup(method, path string) (*MatchedRoute, bool)
	OtherMethods(method, path string) []string
}

Router represents a swagger aware router

func DefaultRouter

func DefaultRouter(spec *spec.Document, api RoutableAPI) Router

DefaultRouter creates a default implemenation of the router