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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.