boneful

Documentation

Index

• Constants
• type Parameter
  • func BodyParameter(name, description string) *Parameter
  • func FormParameter(name, description string) *Parameter
  • func HeaderParameter(name, description string) *Parameter
  • func PathParameter(name, description string) *Parameter
  • func QueryParameter(name, description string) *Parameter
  • func (p *Parameter) AllowMultiple(multiple bool) *Parameter
  • func (p *Parameter) AllowableValues(values map[string]string) *Parameter
  • func (p *Parameter) Data() ParameterData
  • func (p *Parameter) DataFormat(formatName string) *Parameter
  • func (p *Parameter) DataType(typeName string) *Parameter
  • func (p *Parameter) DefaultValue(stringRepresentation string) *Parameter
  • func (p *Parameter) Description(doc string) *Parameter
  • func (p *Parameter) Kind() int
  • func (p *Parameter) Required(required bool) *Parameter
• type ParameterData
  • func (p ParameterData) ParameterKind() string
• type ResponseError
• type Route
  • func (r Route) Reads() string
  • func (r Route) String() string
  • func (r Route) Writes() string
• type RouteBuilder
  • func NewRouteBuilder() *RouteBuilder
  • func (b *RouteBuilder) Build() Route
  • func (b *RouteBuilder) Consumes(mimeTypes ...string) *RouteBuilder
  • func (b *RouteBuilder) Doc(documentation string) *RouteBuilder
  • func (b *RouteBuilder) Method(method string) *RouteBuilder
  • func (b *RouteBuilder) Notes(notes string) *RouteBuilder
  • func (b *RouteBuilder) Operation(name string) *RouteBuilder
  • func (b *RouteBuilder) Param(parameter *Parameter) *RouteBuilder
  • func (b RouteBuilder) ParameterNamed(name string) (p *Parameter)
  • func (b *RouteBuilder) Path(subPath string) *RouteBuilder
  • func (b *RouteBuilder) Produces(mimeTypes ...string) *RouteBuilder
  • func (b *RouteBuilder) Reads(sample interface{}) *RouteBuilder
  • func (b *RouteBuilder) Returns(code int, message string, model interface{}) *RouteBuilder
  • func (b *RouteBuilder) To(function http.HandlerFunc) *RouteBuilder
  • func (b *RouteBuilder) Writes(sample interface{}) *RouteBuilder
• type Service
  • func (s *Service) DELETE(subPath string) *RouteBuilder
  • func (s *Service) Doc(plainText string) *Service
  • func (s *Service) Documentation() string
  • func (s *Service) GET(subPath string) *RouteBuilder
  • func (s *Service) GenerateDocumentation(w io.Writer)
  • func (s *Service) GetDocMD(rw http.ResponseWriter, req *http.Request)
  • func (s *Service) HEAD(subPath string) *RouteBuilder
  • func (s *Service) Method(httpMethod string) *RouteBuilder
  • func (s *Service) Mux() *bone.Mux
  • func (s *Service) PATCH(subPath string) *RouteBuilder
  • func (s *Service) POST(subPath string) *RouteBuilder
  • func (s *Service) PUT(subPath string) *RouteBuilder
  • func (s *Service) Path(root string) *Service
  • func (s *Service) RootPath() string
  • func (s *Service) Route(builder *RouteBuilder) *Service
  • func (s *Service) Routes() []Route

Constants

const (
	// PathParameterKind = indicator of Request parameter type "path"
	PathParameterKind = iota

	// QueryParameterKind = indicator of Request parameter type "query"
	QueryParameterKind

	// BodyParameterKind = indicator of Request parameter type "body"
	BodyParameterKind

	// HeaderParameterKind = indicator of Request parameter type "header"
	HeaderParameterKind

	// FormParameterKind = indicator of Request parameter type "form"
	FormParameterKind
)

Types

type Parameter

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

Parameter is for documententing the parameter used in a Http Request

func BodyParameter

func BodyParameter(name, description string) *Parameter

BodyParameter creates a new Parameter of kind Body for documentation purposes. It is initialized as required without a DataType.

func FormParameter

func FormParameter(name, description string) *Parameter

FormParameter creates a new Parameter of kind Form (using application/x-www-form-urlencoded) for documentation purposes. It is initialized as required with string as its DataType.

func HeaderParameter

func HeaderParameter(name, description string) *Parameter

HeaderParameter creates a new Parameter of kind (Http) Header for documentation purposes. It is initialized as not required with string as its DataType.

func PathParameter

func PathParameter(name, description string) *Parameter

PathParameter creates a new Parameter of kind Path for documentation purposes. It is initialized as required with string as its DataType.

func QueryParameter

func QueryParameter(name, description string) *Parameter

QueryParameter creates a new Parameter of kind Query for documentation purposes. It is initialized as not required with string as its DataType.

func (*Parameter) AllowMultiple

func (p *Parameter) AllowMultiple(multiple bool) *Parameter

AllowMultiple sets the allowMultiple field and returns the receiver

func (*Parameter) AllowableValues

func (p *Parameter) AllowableValues(values map[string]string) *Parameter

AllowableValues sets the allowableValues field and returns the receiver

func (*Parameter) Data

func (p *Parameter) Data() ParameterData

Data returns the state of the Parameter

func (*Parameter) DataFormat

func (p *Parameter) DataFormat(formatName string) *Parameter

DataFormat sets the dataFormat field for Swagger UI

func (*Parameter) DataType

func (p *Parameter) DataType(typeName string) *Parameter

DataType sets the dataType field and returns the receiver

func (*Parameter) DefaultValue

func (p *Parameter) DefaultValue(stringRepresentation string) *Parameter

DefaultValue sets the default value field and returns the receiver

func (*Parameter) Description

func (p *Parameter) Description(doc string) *Parameter

Description sets the description value field and returns the receiver

func (*Parameter) Kind

func (p *Parameter) Kind() int

Kind returns the parameter type indicator (see const for valid values)

func (*Parameter) Required

func (p *Parameter) Required(required bool) *Parameter

Required sets the required field and returns the receiver

type ParameterData

type ParameterData struct {
	Name, Description, DataType, DataFormat string
	Kind                                    int
	Required                                bool
	AllowableValues                         map[string]string
	AllowMultiple                           bool
	DefaultValue                            string
}

ParameterData represents the state of a Parameter. It is made public to make it accessible to e.g. the Swagger package.

func (ParameterData) ParameterKind

func (p ParameterData) ParameterKind() string

type ResponseError

type ResponseError struct {
	Code    int
	Message string
	Model   interface{}
}

type Route

type Route struct {
	Method  string
	Path    string // webservice root path + described path
	Handler http.HandlerFunc

	// documentation
	Doc            string
	Notes          string
	Operation      string
	Consumes       []string
	Produces       []string
	ParameterDocs  []*Parameter
	ResponseErrors map[int]ResponseError
	ReadSample     interface{} // models an example request payload
	WriteSample    interface{} // models an example response payload
	// contains filtered or unexported fields
}

Route binds a Method and Path to a handler. It also holds the documentation for the route.

func (Route) Reads

func (r Route) Reads() string

func (Route) String

func (r Route) String() string

func (Route) Writes

func (r Route) Writes() string

type RouteBuilder

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

func NewRouteBuilder

func NewRouteBuilder() *RouteBuilder

func (*RouteBuilder) Build

func (b *RouteBuilder) Build() Route

Build creates a new Route using the specification details collected by the RouteBuilder

func (*RouteBuilder) Consumes

func (b *RouteBuilder) Consumes(mimeTypes ...string) *RouteBuilder

Consumes specifies what MIME types can be consumes ; the Accept Http header must matched any of these

func (*RouteBuilder) Doc

func (b *RouteBuilder) Doc(documentation string) *RouteBuilder

Doc tells what this route is all about. Optional. Both Doc and Notes will remove leading whitespace after a newline so that you can indent the doc text for prettier source code.

func (*RouteBuilder) Method

func (b *RouteBuilder) Method(method string) *RouteBuilder

Method specifies what HTTP method to match. Required.

func (*RouteBuilder) Notes

func (b *RouteBuilder) Notes(notes string) *RouteBuilder

A verbose explanation of the operation behavior. Optional.

func (*RouteBuilder) Operation

func (b *RouteBuilder) Operation(name string) *RouteBuilder

Operation allows you to document what the acutal method/function call is of the Route. Unless called, the operation name is derived from the http.Handler set using To(..).

func (*RouteBuilder) Param

func (b *RouteBuilder) Param(parameter *Parameter) *RouteBuilder

Param allows you to document the parameters of the Route. It adds a new Parameter (does not check for duplicates).

func (RouteBuilder) ParameterNamed

func (b RouteBuilder) ParameterNamed(name string) (p *Parameter)

ParameterNamed returns a Parameter already known to the RouteBuilder. Returns nil if not. Use this to modify or extend information for the Parameter (through its Data()).

func (*RouteBuilder) Path

func (b *RouteBuilder) Path(subPath string) *RouteBuilder

Path specifies the relative (w.r.t WebService root path) URL path to match. Default is "/".

func (*RouteBuilder) Produces

func (b *RouteBuilder) Produces(mimeTypes ...string) *RouteBuilder

Produces specifies what MIME types can be produced ; the matched one will appear in the Content-Type Http header.

func (*RouteBuilder) Reads

func (b *RouteBuilder) Reads(sample interface{}) *RouteBuilder

Reads tells what resource type will be read from the request payload. Optional. A parameter of type "body" is added ,required is set to true and the dataType is set to the qualified name of the sample's type.

func (*RouteBuilder) Returns

func (b *RouteBuilder) Returns(code int, message string, model interface{}) *RouteBuilder

Returns allows you to document what responses (errors or regular) can be expected. The model parameter is optional ; either pass a struct instance or use nil if not applicable.

func (*RouteBuilder) To

func (b *RouteBuilder) To(function http.HandlerFunc) *RouteBuilder

To bind the route to a function. If this route is matched with the incoming Http Request then call this function with the *Request,*Response pair. Required.

func (*RouteBuilder) Writes

func (b *RouteBuilder) Writes(sample interface{}) *RouteBuilder

Writes tells what resource type will be written as the response payload. Optional.

type Service

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

func (*Service) DELETE

func (s *Service) DELETE(subPath string) *RouteBuilder

DELETE is a shortcut for .Method("DELETE").Path(subPath)

func (*Service) Doc

func (s *Service) Doc(plainText string) *Service

Doc is used to set the documentation of this service.

func (*Service) Documentation

func (s *Service) Documentation() string

Documentation returns it.

func (*Service) GET

func (s *Service) GET(subPath string) *RouteBuilder

GET is a shortcut for .Method("GET").Path(subPath)

func (*Service) GenerateDocumentation

func (s *Service) GenerateDocumentation(w io.Writer)

func (*Service) GetDocMD

func (s *Service) GetDocMD(rw http.ResponseWriter, req *http.Request)

func (*Service) HEAD

func (s *Service) HEAD(subPath string) *RouteBuilder

HEAD is a shortcut for .Method("HEAD").Path(subPath)

func (*Service) Method

func (s *Service) Method(httpMethod string) *RouteBuilder

Method creates a new RouteBuilder and initializes its http method

func (*Service) Mux

func (s *Service) Mux() *bone.Mux

func (*Service) PATCH

func (s *Service) PATCH(subPath string) *RouteBuilder

PATCH is a shortcut for .Method("PATCH").Path(subPath)

func (*Service) POST

func (s *Service) POST(subPath string) *RouteBuilder

POST is a shortcut for .Method("POST").Path(subPath)

func (*Service) PUT

func (s *Service) PUT(subPath string) *RouteBuilder

PUT is a shortcut for .Method("PUT").Path(subPath)

func (*Service) Path

func (s *Service) Path(root string) *Service

Path specifies the root URL template path of the WebService. All Routes will be relative to this path.

func (*Service) RootPath

func (s *Service) RootPath() string

RootPath returns the RootPath associated with this WebService. Default "/"

func (*Service) Route

func (s *Service) Route(builder *RouteBuilder) *Service

Route creates a new Route using the RouteBuilder and add to the ordered list of Routes.

func (*Service) Routes

func (s *Service) Routes() []Route

Routes returns the array of routes defined for this service.