routing

README

Routing

Package routing provides a naive router with regular expression support.

When using named sub groups in a regex path, the named groups matched expression will be set on the request's context by it's name. So if you register the route ^/foo/(?P[0-9]+)$ (escaped angle brackets for Github flavoured markdown: ^/foo/(?P<param>[0-9]+)$), you can get it by doing *http.Request.Context().Value("param") in your handler.

The routes can be supplied with metadata though a fluent API to generate HTML documentation.

If regular expression matchings overlap, they take precedence by the order they have been added.

Documentation

Overview

Package routing provides a naive router with regular expression support.

When using named sub groups in a regex path, the named groups matched expression will be set on the request's context by it's name. So if you register the route ^/foo/(?P<param>[0-9]+)$, you can get it by doing *http.Request.Context().Value("param") in your handler.

The routes can be supplied with metadata though a fluent API to generate HTML documentation.

If regular expression matchings overlap, they take precedence by the order they have been added.

Index

• func WriteDocs(out io.Writer, name string, version string, baseURL string, router *Router) error
• type API
• type Body
  • func NewBody(contentType, name string, example interface{}) *Body
  • func NewResponse(contentType, name string, example interface{}) *Body
• type ErrInvalidRouteMatchType
  • func (e *ErrInvalidRouteMatchType) Error() string
• type HTTPArgument
  • func NewHTTPArgument(name string, example interface{}) *HTTPArgument
• type MatchType
• type Middleware
• type Middlewarer
• type PathArgument
  • func NewPathArgument(name string, example interface{}) *PathArgument
• type QueryParameter
  • func NewQueryParameter(name string, example interface{}) *QueryParameter
• type Route
  • func NewRexRoute(p string) *Route
  • func NewRoute(p string) *Route
  • func (r *Route) AddMiddleware(mw Middlewarer) *Route
  • func (r *Route) AddPathArgument(a *PathArgument) *Route
  • func (r *Route) AddQueryParameter(p *QueryParameter) *Route
  • func (route *Route) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (r *Route) SetDescription(d string) *Route
  • func (r *Route) SetHandler(h http.Handler) *Route
  • func (r *Route) SetHandlerFunc(h http.HandlerFunc) *Route
  • func (r *Route) SetMethod(m string) *Route
  • func (r *Route) SetRequestBody(b *Body) *Route
  • func (r *Route) SetResponse(b *Body) *Route
  • func (r *Route) SetTag(t string) *Route
• type Router
  • func NewRouter() *Router
  • func (r *Router) Add(route *Route) error
  • func (r *Router) Match(method, path string) *Route
  • func (r *Router) RoutesForTag(t string) []*Route
  • func (router *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (r *Router) Tags() []string

Functions

func WriteDocs

func WriteDocs(
	out io.Writer,
	name string,
	version string,
	baseURL string,
	router *Router,
) error

Types

type API

type API struct {
	Name    string
	Version string
	BaseURL string
	Router  *Router
}

Type APIStruct holds data needed to render the HTML document.

type Body

type Body struct {
	*HTTPArgument

	ContentType string
}

func NewBody

func NewBody(contentType, name string, example interface{}) *Body

func NewResponse

func NewResponse(contentType, name string, example interface{}) *Body

type ErrInvalidRouteMatchType

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

func (*ErrInvalidRouteMatchType) Error

func (e *ErrInvalidRouteMatchType) Error() string

type HTTPArgument

type HTTPArgument struct {
	Name    string
	Example interface{}
}

func NewHTTPArgument

func NewHTTPArgument(name string, example interface{}) *HTTPArgument

type MatchType

type MatchType int

type Middleware

type Middleware func(http.Handler) http.Handler

type Middlewarer

type Middlewarer interface {
	Middleware() Middleware
	Name() string
	Description() string
}

Middlewarer represents the interface for middlewares that can be documented automatically.

type PathArgument

type PathArgument HTTPArgument

func NewPathArgument

func NewPathArgument(name string, example interface{}) *PathArgument

type QueryParameter

type QueryParameter HTTPArgument

func NewQueryParameter

func NewQueryParameter(name string, example interface{}) *QueryParameter

type Route

type Route struct {
	MatchType       MatchType
	Rex             *regexp.Regexp
	Handler         http.Handler
	RequestBody     *Body
	Response        *Body
	QueryParameters []*QueryParameter
	PathArguments   []*PathArgument
	Method          string
	Middleware      []Middlewarer
	Tag             string
	Description     string
}

Type Route represents a path and is registered with the Router.

A Route exposesa a fluid api to set metadata that is used to create an HTML document.

func NewRexRoute

func NewRexRoute(p string) *Route

func NewRoute

func NewRoute(p string) *Route

func (*Route) AddMiddleware

func (r *Route) AddMiddleware(mw Middlewarer) *Route

AddMiddleware adds a middleware to a route. Middlewares are sorted by their name.

func (*Route) AddPathArgument

func (r *Route) AddPathArgument(a *PathArgument) *Route

func (*Route) AddQueryParameter

func (r *Route) AddQueryParameter(p *QueryParameter) *Route

func (*Route) ServeHTTP

func (route *Route) ServeHTTP(
	w http.ResponseWriter,
	r *http.Request,
)

func (*Route) SetDescription

func (r *Route) SetDescription(d string) *Route

func (*Route) SetHandler

func (r *Route) SetHandler(h http.Handler) *Route

func (*Route) SetHandlerFunc

func (r *Route) SetHandlerFunc(h http.HandlerFunc) *Route

func (*Route) SetMethod

func (r *Route) SetMethod(m string) *Route

func (*Route) SetRequestBody

func (r *Route) SetRequestBody(b *Body) *Route

func (*Route) SetResponse

func (r *Route) SetResponse(b *Body) *Route

func (*Route) SetTag

func (r *Route) SetTag(t string) *Route

type Router

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

func NewRouter

func NewRouter() *Router

func (*Router) Add

func (r *Router) Add(route *Route) error

func (*Router) Match

func (r *Router) Match(method, path string) *Route

Match will search and return the route registered for the HTTP method and URL path.

Returns nil if none found.

If two regex pattern match, the one added sooner takes precedence.

func (*Router) RoutesForTag

func (r *Router) RoutesForTag(t string) []*Route

RoutesFor Tag returns all routes for t sorted by path.

It returns an empty slice even if there are no routes for t.

func (*Router) ServeHTTP

func (router *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP satisfied the net/http.Handler interface.

func (*Router) Tags

func (r *Router) Tags() []string