definition

package
v0.1.0-alpha.0 Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2018 License: Apache-2.0 Imports: 3 Imported by: 226

Documentation

Index

Constants

View Source 
const (
	// acceptTypeAll indicates a accept type from http request.
	// It means client can receive any content.
	// Request content type in header "Content-Type" must not set to "*/*".
	// It only can exist in request header "Accept".
	// In most time, it locate at the last element of "Accept".
	// It's default value if client have not set "Accept" header.
	MIMEAll         = "*/*"
	MIMENone        = ""
	MIMEText        = "text/plain"
	MIMEJSON        = "application/json"
	MIMEXML         = "application/xml"
	MIMEOctetStream = "application/octet-stream"
	MIMEURLEncoded  = "application/x-www-form-urlencoded"
	MIMEFormData    = "multipart/form-data"
)

MIME types

Variables

This section is empty.

Functions

This section is empty.

Types

type Chain 

type Chain interface {
	// Continue continues to execute the next subsequent actions.
	Continue(context.Context) error
}

Chain contains all subsequent actions.

type Definition 

type Definition struct {
	// Method is definition method.
	Method Method
	// Consumes indicates how many content types the handler can consume.
	// It will override parent descriptor's consumes.
	Consumes []string
	// Produces indicates how many content types the handler can produce.
	// It will override parent descriptor's produces.
	Produces []string
	// Function is a function handler. It must be func type.
	Function interface{}
	// Parameters describes function parameters.
	Parameters []Parameter
	// Results describes function retrun values.
	Results []Result
	// Description describes the API handler.
	Description string
	// Examples contains many examples for the API handler.
	Examples []Example
}

Definition defines an API handler.

func AsyncCreateDefinitionFor 

func AsyncCreateDefinitionFor(f interface{}, description string) Definition

AsyncCreateDefinitionFor creates a defnition for method async create.

func AsyncDeleteDefinitionFor 

func AsyncDeleteDefinitionFor(f interface{}, description string) Definition

AsyncDeleteDefinitionFor creates a defnition for method async delete.

func AsyncPatchDefinitionFor 

func AsyncPatchDefinitionFor(f interface{}, description string) Definition

AsyncPatchDefinitionFor creates a defnition for method async patch.

func AsyncUpdateDefinitionFor 

func AsyncUpdateDefinitionFor(f interface{}, description string) Definition

AsyncUpdateDefinitionFor creates a defnition for method async update.

func CreateDefinitionFor 

func CreateDefinitionFor(f interface{}, description string) Definition

CreateDefinitionFor creates a defnition for method create.

func DeleteDefinitionFor 

func DeleteDefinitionFor(f interface{}, description string) Definition

DeleteDefinitionFor creates a defnition for method delete.

func GetDefinitionFor 

func GetDefinitionFor(f interface{}, description string) Definition

GetDefinitionFor creates a defnition for method get.

func ListDefinitionFor 

func ListDefinitionFor(f interface{}, description string) Definition

ListDefinitionFor creates a defnition for method list.

func NewDefinition 

func NewDefinition(method Method, f interface{}, description string) Definition

NewDefinition creates a definition.

func PatchDefinitionFor 

func PatchDefinitionFor(f interface{}, description string) Definition

PatchDefinitionFor creates a defnition for method patch.

func UpdateDefinitionFor 

func UpdateDefinitionFor(f interface{}, description string) Definition

UpdateDefinitionFor creates a defnition for method update.

func (Definition) Consume 

func (d Definition) Consume(cs ...string) Definition

Consume adds consumes.

func (Definition) Example 

func (d Definition) Example(es ...Example) Definition

Example adds examples.

func (Definition) Parameter 

func (d Definition) Parameter(ps ...Parameter) Definition

Parameter adds parameters.

func (Definition) Produce 

func (d Definition) Produce(cs ...string) Definition

Produce adds produces.

func (Definition) Result 

func (d Definition) Result(rs ...Result) Definition

Result adds results.

type Descriptor 

type Descriptor struct {
	// Path is the url path. It will inherit parent's path.
	//
	// If parent path is "/api/v1", current is "/some",
	// It means current definitions handles "/api/v1/some".
	Path string
	// Consumes indicates content types that current definitions
	// and child definitions can consume.
	// It will override parent descriptor's consumes.
	Consumes []string
	// Produces indicates content types that current definitions
	// and child definitions can produce.
	// It will override parent descriptor's produces.
	Produces []string
	// Middlewares contains path middlewares.
	Middlewares []Middleware
	// Definitions contains definitions for current path.
	Definitions []Definition
	// Children is used to place sub-descriptors.
	Children []Descriptor
	// Description describes the usage of the path.
	Description string
}

Descriptor describes a descriptor for API definitions.

func DescriptorFor 

func DescriptorFor(path string, description string) Descriptor

DescriptorFor creates a descriptor.

func SimpleDescriptor 

func SimpleDescriptor(method Method, path string, f interface{}) Descriptor

SimpleDescriptor creates a simple descriptor for handler. The descriptor consumes all content types and produces all accept types.

func (Descriptor) Consume 

func (d Descriptor) Consume(cs ...string) Descriptor

Consume adds consumes.

func (Descriptor) Definition 

func (d Descriptor) Definition(defs ...Definition) Descriptor

Definition adds definitions.

func (Descriptor) Descriptor 

func (d Descriptor) Descriptor(descs ...Descriptor) Descriptor

Descriptor adds descriptors as children.

func (Descriptor) Middleware 

func (d Descriptor) Middleware(ms ...Middleware) Descriptor

Middleware adds middlewares.

func (Descriptor) Produce 

func (d Descriptor) Produce(ps ...string) Descriptor

Produce adds produces.

type Destination 

type Destination string

Destination indicates the target type to place function results. 

const (
	// Meta means result will be set into the header of response.
	Meta Destination = "Meta"
	// Data means result will be set into the body of response.
	Data Destination = "Data"
	// Error means the result is an error and should be treated specially.
	// An error occurs indicates that there is no data to return. So the
	// error should be treated as data and be writed back to client.
	Error Destination = "Error"
)

type Example 

type Example struct {
	// Description describes the example.
	Description string
	// Instance is a custom data.
	Instance interface{}
}

Example is just an example.

type Method 

type Method string

Method is an alternative of HTTP method. It's more clearer than HTTP method. A definition method binds a certain HTTP method and a success status code. 

const (
	// List binds to http.MethodGet and code http.StatusOK(200).
	List Method = "List"
	// Get binds to http.MethodGet and code http.StatusOK(200).
	Get Method = "Get"
	// Create binds to http.MethodPost and code http.StatusCreated(201).
	Create Method = "Create"
	// Update binds to http.MethodPut and code http.StatusOK(200).
	Update Method = "Update"
	// Patch binds to http.MethodPatch and code http.StatusOK(200).
	Patch Method = "Patch"
	// Delete binds to http.MethodDelete and code http.StatusNoContent(204).
	Delete Method = "Delete"
	// AsyncCreate binds to http.MethodPost and code http.StatusAccepted(202).
	AsyncCreate Method = "AsyncCreate"
	// AsyncUpdate binds to http.MethodPut and code http.StatusAccepted(202).
	AsyncUpdate Method = "AsyncUpdate"
	// AsyncPatch binds to http.MethodPatch and code http.StatusAccepted(202).
	AsyncPatch Method = "AsyncPatch"
	// AsyncDelete binds to http.MethodDelete and code http.StatusAccepted(202).
	AsyncDelete Method = "AsyncDelete"
)

type Middleware 

type Middleware func(context.Context, Chain) error

Middleware describes the form of middlewares. If you want to carry on, call Chain.Continue() and pass the context.

type Operator 

type Operator interface {
	// Kind indicates operator type.
	Kind() string
	// In returns the type of the only object parameter of operator.
	// The type must be a concrete struct or built-in type. It should
	// not be interface unless it's a file or stream reader.
	In() reflect.Type
	// Out returns the type of the only object result of operator.
	// The type must be a concrete struct or built-in type. It should
	// not be interface unless it's a file or stream reader.
	Out() reflect.Type
	// Operate operates an object and return one.
	Operate(ctx context.Context, field string, object interface{}) (interface{}, error)
}

Operator is used to operate an object and return an replacement object.

For example: 

A converter:
  type ConverterForAnObject struct{}
  func (c *ConverterForAnObject) Kind() {return "converter"}
  func (c *ConverterForAnObject) In() reflect.Type {return definition.TypeOf(&ObjectV1{})}
  func (c *ConverterForAnObject) Out() reflect.Type {return definition.TypeOf(&ObjectV2{})}
  func (c *ConverterForAnObject) Operate(ctx context.Context, object interface{}) (interface{}, error) {
      objV2, err := convertObjectV1ToObjectV2(object.(*ObjectV1))
      return objV2, err
  }

A validator:
  type ValidatorForAnObject struct{}
  func (c *ValidatorForAnObject) Kind() {return "validator"}
  func (c *ValidatorForAnObject) In() reflect.Type {return definition.TypeOf(&Object{})}
  func (c *ValidatorForAnObject) Out() reflect.Type {return definition.TypeOf(&Object{})}
  func (c *ValidatorForAnObject) Operate(ctx context.Context, object interface{}) (interface{}, error) {
      if err := validate(object.(*Object)); err != nil {
          return nil, err
      }
      return object, nil
  }

func NewOperator 

func NewOperator(kind string, in, out reflect.Type, f func(ctx context.Context, field string, object interface{}) (interface{}, error)) Operator

NewOperator creates operator by function. function must has signature: 

func f(context.Context, AnyType) (AnyType, error)

AnyType can be any type in go. But struct type and built-in data type is recommended.

func OperatorFunc 

func OperatorFunc(kind string, f interface{}) Operator

OperatorFunc creates operator by function. function must has signature: 

func f(context.Context, AnyType) (AnyType, error)

AnyType can be any type in go. But struct type and built-in data type is recommended.

type Parameter 

type Parameter struct {
	// Source is the parameter value generated from.
	Source Source
	// Name is the name to get value from a request.
	// ex. a query name, a header key, etc.
	Name string
	// Default value is used when a request does not provide a value
	// for the parameter.
	Default interface{}
	// Operators can modify and validate the target value.
	// Parameter value is passed to the first operator, then
	// previous operator's result is as next operator's parameter.
	// The result of last operator will be passed to target function.
	Operators []Operator
	// Description describes the parameter.
	Description string
}

Parameter describes a function parameter.

func AutoParameterFor 

func AutoParameterFor(description string) Parameter

AutoParameterFor creates a path parameter

func BodyParameterFor 

func BodyParameterFor(description string) Parameter

BodyParameterFor creates a path parameter

func FileParameterFor 

func FileParameterFor(name string, description string) Parameter

FileParameterFor creates a path parameter

func FormParameterFor 

func FormParameterFor(name string, description string) Parameter

FormParameterFor creates a path parameter

func HeaderParameterFor 

func HeaderParameterFor(name string, description string) Parameter

HeaderParameterFor creates a path parameter

func ParameterFor 

func ParameterFor(source Source, name string, description string) Parameter

ParameterFor creates a simple parameter.

func PathParameterFor 

func PathParameterFor(name string, description string) Parameter

PathParameterFor creates a path parameter

func PrefabParameterFor 

func PrefabParameterFor(name string, description string) Parameter

PrefabParameterFor creates a path parameter

func QueryParameterFor 

func QueryParameterFor(name string, description string) Parameter

QueryParameterFor creates a path parameter

func (Parameter) DefaultValue 

func (p Parameter) DefaultValue(value interface{}) Parameter

DefaultValue sets default value for the parameter.

func (Parameter) Operator 

func (p Parameter) Operator(operators ...Operator) Parameter

Operator adds operators to current parameter.

type Result 

type Result struct {
	// Destination is the target for the result. Different types make different behavior.
	Destination Destination
	// Operators can modify the result value.
	// Result value is passed to the first operator, then
	// previous operator's result is as next operator's parameter.
	// The result of last operator will be passed to destination handler.
	Operators []Operator
	// Description describes the result.
	Description string
}

Result describes how to handle a result from function results.

func DataErrorResults 

func DataErrorResults(description string) []Result

DataErrorResults returns the most frequently-used results. Definition function should have two results. The first is any type for data, and the last is error.

func DataResultFor 

func DataResultFor(description string) Result

DataResultFor creates data result.

func ErrorResult 

func ErrorResult() Result

ErrorResult creates data result.

func MetaResultFor 

func MetaResultFor(description string) Result

MetaResultFor creates meta result.

func ResultFor 

func ResultFor(dest Destination, description string) Result

ResultFor creates a simple result.

func (Result) Operator 

func (r Result) Operator(operators ...Operator) Result

Operator adds operators to current result.

type Source 

type Source string

Source indicates which place a value is from. 

const (
	// Path means value is from URL path.
	Path Source = "Path"
	// Query means value is from URL query string.
	Query Source = "Query"
	// Header means value is from request header.
	Header Source = "Header"
	// Form means value is from request body and content type must be
	// "application/x-www-form-urlencoded" and "multipart/form-data".
	Form Source = "Form"
	// File means value is from request body and content type must be
	// "multipart/form-data".
	File Source = "File"
	// Body means value is from request body.
	Body Source = "Body"
	// Auto identifies a struct and generate field values by field tag.
	//
	// Tag name is "source". Its value format is "Source,Name".
	//
	// ex.
	// type Example struct {
	//     Start       int    `source:"Query,start"`
	//     ContentType string `source:"Header,Content-Type"`
	// }
	Auto Source = "Auto"
	// Prefab means value is from a prefab generator.
	// A prefab combines data to generate value.
	Prefab Source = "Prefab"
)

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.