Documentation
¶
Overview ¶
Package kit provides a code generator to generate endpoints and http handlers for an interface. For the code generator to work, the following requirements should be met:
- Interface methods do not contain function types, channel types or anonymous structs as parameter or return values.
- The source file that contains the interface should not import any types that are used in the interface definition using ".", i.e. (import them without a prefix/qualifier).
- Every interface method has a context.Context as the first parameter.
- Every interface method has 1 or 2 return values, where the last one is always "error".
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EndpointSpecification ¶
type EndpointSpecification struct {
// name of this endpoint, defaults to the name of the method
Name string `json:"name"`
// specifies how the http handler for this endpoint is generated
HttpSpec HttpSpec `json:"http"`
}
Specification to create a single endpoint for an inteface method.
type EndpointSpecifications ¶
type EndpointSpecifications struct {
// the interface method to generate endpoints for
Method parse.Method
EndpointSpecs []EndpointSpecification `json:"endpoints"`
// How the values from the interface method are obtained from an http request,
// only used if http handlers are generated.
// Since we expect the first parameter of an interface method to be a "context.Context", the length of this slice
// should equal len(Method.Params) - 1.
// TODO we could let every endpoint for this method define their own http params, which would result in multiple http decode funcs, but this is not necessary for now.
HttpParams []HttpParamType `json:"httpParams"`
}
Defines the endpoints created for a single interface method. We can generate multiple endpoints for the same interface method, e.g. to use different permission/authentication middlewares or different http urls.
func (EndpointSpecifications) IsValid ¶
func (e EndpointSpecifications) IsValid() error
type HttpParamType ¶
type HttpParamType string
HttpParamType represents how the parameters of an interface method should be obtained from a http request. E.g. by parsing the request body as json or extracting the parameter from the url path or query parameters.
const HttpTypeJson HttpParamType = "json"
const HttpTypeQuery HttpParamType = "query"
const HttpTypeUrl HttpParamType = "url"
type HttpSpec ¶
type HttpSpec struct {
// url
Path string `json:"path"`
// http method, e.g. "GET", "POST", ...
Method string `json:"method"`
// http code for the response on success
SuccessCode int `json:"successCode"`
}
Defines how a http handler is generated for an endpoint.
type KitGenSpecification ¶
type KitGenSpecification struct {
//the interface for which code should be generated
Interface parse.Interface
//go module the interface belongs to
Module parse.Module
// if false, nothing will be generated
GenerateEndpoints bool
// if false, will not generate http handlers for endpoints
GenerateHttp bool
// package name used for generated endpoints
// can be a full package path or relative to the module name
// If empty will not generate endpoints.
EndpointPackage string `json:"endpointPackage"`
// full path of the package that will contain the generated endpoint code
// we need this to later import this package to e.g. generate http handlers
EndpointPackageFullPath string
// output file for endpoint code
EndpointOutput string `json:"endpointOutput"`
// Package name used for generated http handlers.
// If empty will not generate anything.
HttpPackage string `json:"httpPackage"`
HttpPackageFullPath string
// output file for http code
HttpOutput string `json:"httpOutput"`
// each element specifies the endpoints to generate for an interface method
Endpoints []EndpointSpecifications
}
KitGenSpecification defines what the code generator should generate. It is typically constructed by reading source code annotations on e.g. an interface or method and configuration from the command line or a configuration file.
func SpecFromAnnotations ¶
func SpecFromAnnotations(i parse.Interface, m parse.Module, a annotations.InterfaceAnnotation) (KitGenSpecification, error)
func (KitGenSpecification) ContainsDuplicateEndpointName ¶
func (spec KitGenSpecification) ContainsDuplicateEndpointName() error
func (KitGenSpecification) IsValid ¶
func (spec KitGenSpecification) IsValid() error
Checks if a given specification is valid. A specification is not valid if one of the following conditions is not satisfied:
- there cannot be two endpoints with the same name
- any interface method (for which at least one endpoint is defined) must have a context.Context value as first parameter
- any interface method (for which at least one endpoint is defined) must have at most two return values and last return value must be of type error
- if http code is generated, endpoints should have http method, path and success code set
type KitGenerator ¶
type KitGenerator struct {
Spec KitGenSpecification
// contains filtered or unexported fields
}
func NewKitGenerator ¶
func NewKitGenerator(spec KitGenSpecification) *KitGenerator
Source Files