boneful

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 20, 2019 License: MIT Imports: 8 Imported by: 4

README

boneful

A wrapper for the bone router that provides a clean and fast way to document endpoints.

See doc.go for why we did it this way, and run go test to generate a simple sample doc file.

This work was originally done at the Achievement Network and open-sourced there as part of the go-util package.

This updates it and pulls it into its own repository.

You can see examples of it in use at AchievementNetwork's github in the Vasco and Static projects.

Documentation

Index

Constants

View Source
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
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Parameter

type Parameter struct {
	D *ParameterData `json:"data"`
}

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            string            `json:"name"`
	Description     string            `json:"description"`
	DataType        string            `json:"datatype"`
	DataFormat      string            `json:"dataformat"`
	Kind            int               `json:"kind"`
	Required        bool              `json:"required"`
	AllowableValues map[string]string `json:"allowablevalues"`
	AllowMultiple   bool              `json:"allowmultiple"`
	DefaultValue    string            `json:"defaultvalue"`
}

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

ParameterKind returns the type of this parameter as a string.

type ResponseError

type ResponseError struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Model   interface{} `json:"model"`
}

ResponseError is an error type returned from this API

type Route

type Route struct {
	Method  string           `json:"method"`
	Path    string           `json:"path"` // webservice root path + described path
	Handler http.HandlerFunc `json:"-"`

	// documentation
	Doc            string                `json:"doc"`
	Notes          string                `json:"notes"`
	Operation      string                `json:"operation"`
	Consumes       []string              `json:"consumes"`
	Produces       []string              `json:"produces"`
	ParameterDocs  []*Parameter          `json:"parms"`
	ResponseErrors map[int]ResponseError `json:"-"`
	ReadSample     interface{}           `json:"-"` // models an example request payload
	WriteSample    interface{}           `json:"-"` // 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) CodeFormat added in v1.1.0

func (r Route) CodeFormat() string

CodeFormat generates the marker for file contents for a code block in Markdown

func (Route) Reads

func (r Route) Reads() string

Reads returns formatted example content for a Reads value

func (Route) String

func (r Route) String() string

func (Route) Writes

func (r Route) Writes() string

Writes returns formatted example content for a Writes value

type RouteBuilder

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

RouteBuilder is the type that is managed by boneful. It contains all of the information about a route.

func NewRouteBuilder

func NewRouteBuilder() *RouteBuilder

NewRouteBuilder constructs an empty 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 consumed ; the Accept Http header must match one 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

Notes is 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
}

Service is the base type for what users of the API will manage

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 text of this service. It strips leading whitespace from every line so that you can have attractive indenting in your source files. Markdown will mess with it anyway.

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)

GenerateDocumentation is used to spit out markdown format of docs.

func (*Service) GenerateJSONDoc

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

GenerateJSONDoc emits JSON-formatted documentation info

func (*Service) GetDocMD

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

GetDocMD is a handler for markdown documentation.

func (*Service) GetJSONDoc

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

GetJSONDoc is a handler to return JSON documentation

func (*Service) HEAD

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

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

func (*Service) HealthCheck added in v1.1.0

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

HealthCheck is a rudimentary endpoint that simply returns "OK". If you want something more sophisticated, simply write your own and put it under the /health endpoint.

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

Mux returns a multiplexer that can be used as a master handler to route requests to the appropriate handler.

func (*Service) OPTIONS

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

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL