Documentation ¶
Index ¶
- Variables
- func DefaultSchemaIdentifier(t reflect.Type) string
- func GetErrCode(err error) (string, bool)
- func ReflectSpec(root openapi3.T, fns []Function, opts ...reflectSpecOpt) (openapi3.T, error)
- func SetErrCode(err error, code string) error
- func ShortSchemaIdentifier(t reflect.Type) string
- func WithSchemaIdentifier(namer SchemaIdentifier) reflectSpecOpt
- func WithSchemaMapper(mapper SchemaMapper) reflectSpecOpt
- type Decoder
- type DecoderFunc
- type Encoder
- type EncoderFunc
- type Encoding
- type ErrWithCode
- type ErrorHandler
- type Function
- func Func[TReq any, TRes any](mountpoint string, fn func(ctx context.Context, req TReq) (TRes, error)) Function
- func FuncNullary[TRes any](mountpoint string, fn func(ctx context.Context) (TRes, error)) Function
- func FuncNullaryVoid(mountpoint string, fn func(ctx context.Context) error) Function
- func FuncVoid[TReq any](mountpoint string, fn func(ctx context.Context, req TReq) error) Function
- type Handler
- type HandlerOption
- func WithDefaultSpec(spec *openapi3.T) HandlerOption
- func WithEncodings(encodings ...Encoding) HandlerOption
- func WithErrorHandler(h ErrorHandler) HandlerOption
- func WithPathPrefix(prefixPath string) HandlerOption
- func WithReflection(opts ...reflectSpecOpt) HandlerOption
- func WithSwaggerJSONPath(path string) HandlerOption
- func WithSwaggerUI(path string) HandlerOption
- type Middleware
- type SchemaIdentifier
- type SchemaMapper
- type SchemaProvider
- type SwaggerUIHandler
- type Void
- type WithCode
Constants ¶
This section is empty.
Variables ¶
var ErrApplication = errors.New("application error")
var JsonEncoding = Encoding{ MimeType: "application/json", GetEncoder: func(w io.Writer) Encoder { enc := json.NewEncoder(w) return EncoderFunc(func(v any) error { return enc.Encode(v) }) }, GetDecoder: func(r io.Reader) Decoder { dec := json.NewDecoder(r) return DecoderFunc(func(v any) error { return dec.Decode(v) }) }, }
Functions ¶
func DefaultSchemaIdentifier ¶
DefaultSchemaIdentifier creates a schema identifier for the provided type `t` in the form of '<path>.<to>.<my>.<package>.<name>
func GetErrCode ¶
func ReflectSpec ¶
ReflectSpec reflects all provided exposed functions `fns` and generates an openapi3 specification. The provided spec is the template for the resulting specification. Use it e.g. to define the spec info or additional schemas and operations
func SetErrCode ¶
func ShortSchemaIdentifier ¶
ShortSchemaIdentifier creates a schema identifier for the provided type `t` in the form of '<package.<name>'
func WithSchemaIdentifier ¶
func WithSchemaIdentifier(namer SchemaIdentifier) reflectSpecOpt
WithSchemaIdentifier sets an alternative SchemaIdentifier. Default: DefaultSchemaIdentifier
func WithSchemaMapper ¶
func WithSchemaMapper(mapper SchemaMapper) reflectSpecOpt
Types ¶
type DecoderFunc ¶
func (DecoderFunc) Decode ¶
func (f DecoderFunc) Decode(v any) error
type EncoderFunc ¶
func (EncoderFunc) Encode ¶
func (f EncoderFunc) Encode(v any) error
type Encoding ¶
type Encoding struct { MimeType string GetDecoder func(r io.Reader) Decoder GetEncoder func(w io.Writer) Encoder }
Encoding is used for content negotiating. Request arguments and response values are encoded and decoded with the encoding that is matching the `Content-Type` or `Accept` header.
type ErrWithCode ¶
type ErrWithCode struct {
// contains filtered or unexported fields
}
func (ErrWithCode) Code ¶
func (e ErrWithCode) Code() string
func (ErrWithCode) Error ¶
func (e ErrWithCode) Error() string
type ErrorHandler ¶
type ErrorHandler func(w http.ResponseWriter, enc Encoder, err error) (handled bool)
ErrorHandler is called, when a exposed function returns an error. Returning `handled == true` cancels any further error handling.
type Function ¶
type Function interface { // Name is the name of the exposed function. // The name is part of the operationId in the spec. Name() string // Module is a qualifier, used in the operationId and as tag in the operation. Module() string // Path is the actual path, where the function is registered Path() string // Req returns an empty instance of the functions request argument. // Used for schema reflection. Req() any // Res returns an empty instance of the functions result value. // Used for schema reflection. Res() any // Apply calls the actual function by decoding the http request and passing it to the function Apply(ctx context.Context, dec Decoder) (any, error) }
Function defines a function, that should be registered as RPC endpoint in the Handler. It carries all information, that is necessary to include it as an operation in the openapi spec of the Handler, as well as the actual function wrapped in `Apply`
func Func ¶
func Func[TReq any, TRes any](mountpoint string, fn func(ctx context.Context, req TReq) (TRes, error)) Function
Func creates an Function that can be registered with the Handler. The provided `fn` is then callable at the provided path. If you want to expose a function without an input or output parameter, you can parametrize with Void, use FuncVoid or FuncNullary instead.
func FuncNullary ¶
FuncNullary creates an Function for functions without a request argument. See Func.
func FuncNullaryVoid ¶
FuncNullaryVoid creates an Function for functions without a request argument and return no result. See Func
type Handler ¶
Handler handles RPC requests. See NewHandler
func NewHandler ¶
func NewHandler(fns []Function, options ...HandlerOption) (*Handler, error)
NewHandler creates a http handler, that provides the exposed functions as HTTP POST endpoints. see Handler Requests and responses are encoded with JSON by default. The handler also provides the openapi spec at the path '/swagger.json'
When an exposed function returns an error, the handler will respond with HTTP status 500 Internal Server Error by default. When the error is (see errors.Is) an ErrApplication, the status 422 Unprocessable Entity will be returned instead. Errors can be marked with custom codes SetErrCode, which will be included in the error response. To customize the error handling further, a ErrorHandler can be provided.
type HandlerOption ¶
type HandlerOption func(settings *handlerSettings)
func WithDefaultSpec ¶
func WithDefaultSpec(spec *openapi3.T) HandlerOption
WithDefaultSpec allows you to define a base spec. The handler fills this base spec with the operations and schemas reflected from the exposed functions.
func WithEncodings ¶
func WithEncodings(encodings ...Encoding) HandlerOption
WithEncodings registers additional encodings. Encodings are selected based on the provided "Content-Type" and "Accept" headers
func WithErrorHandler ¶
func WithErrorHandler(h ErrorHandler) HandlerOption
WithErrorHandler registers a custom ErrorHandler
func WithPathPrefix ¶
func WithPathPrefix(prefixPath string) HandlerOption
WithPathPrefix defines the path prefix of the handler. When using it with WithSwaggerUI, make sure that your `Servers` section in the default spec WithDefaultSpec adds this prefix as well
func WithReflection ¶
func WithReflection(opts ...reflectSpecOpt) HandlerOption
WithReflection sets options for the schema reflection
func WithSwaggerJSONPath ¶
func WithSwaggerJSONPath(path string) HandlerOption
WithSwaggerJSONPath overrides the default path (/swagger.json), where the spec is served
func WithSwaggerUI ¶
func WithSwaggerUI(path string) HandlerOption
WithSwaggerUI, adds a SwaggerUI handler at the provided `path`
type SchemaIdentifier ¶
TypeNamers are used to generate a schema identifier for a go type
type SchemaProvider ¶
type SchemaProvider interface {
JSONSchema(gen *openapi3gen.Generator, schemas openapi3.Schemas) (*openapi3.SchemaRef, error)
}
SchemaProvider overrides the schema reflection with the provided custom type
type SwaggerUIHandler ¶
func NewSwaggerUIHandler ¶
func NewSwaggerUIHandler(defaultSpec openapi3.T, fns []Function) *SwaggerUIHandler
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
examples
|
|
exposefx contains helper methods to expose functions to a fx app and to provide the handler
|
exposefx contains helper methods to expose functions to a fx app and to provide the handler |