Documentation
¶
Index ¶
- func Cors(opts ...CORSOption) func(http.Handler) http.Handler
- func Decode[T any](r *http.Request) (T, error)
- func DefaultDocsHTML(openAPIPath string) string
- func Encode(w http.ResponseWriter, _ *http.Request, status int, v any)
- func Optional[T any](req ...T) any
- func WriteDocsHTMLFile(path, openAPIPath string) error
- type CORSOption
- func WithAllowCredentials(enabled bool) CORSOption
- func WithAllowedHeaders(headers ...string) CORSOption
- func WithAllowedMethods(methods ...string) CORSOption
- func WithAllowedOrigins(origins ...string) CORSOption
- func WithExposedHeaders(headers ...string) CORSOption
- func WithMaxAgeSeconds(seconds int) CORSOption
- type CORSOptions
- type DocOpt
- type DocsOptions
- type Guard
- type GuardSpec
- type HandlerMeta
- type NoResponse200
- type NoResponse204
- type NoResponse500
- type OpenAPIContact
- type OpenAPIExternalDocs
- type OpenAPILicense
- type OpenAPIOptions
- type OpenAPIServer
- type OpenAPITag
- type ResponseSpec
- type Route
- type Router
- func (r *Router) AttachLogger(next http.Handler) http.Handler
- func (r *Router) Handle(pattern string, h http.Handler, guards ...Guard)
- func (r *Router) HandleFunc(pattern string, fn func(http.ResponseWriter, *http.Request))
- func (r *Router) HandleTyped(pattern string, h TypedHandler, guards ...Guard)
- func (r *Router) OpenAPI() ([]byte, error)
- func (r *Router) Routes() []Route
- func (r *Router) ServeAllDocs(opts ...ServeAllDocsOpt)
- func (r *Router) ServeClientJS(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeClientJSHash(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeClientPY(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeClientPYHash(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeClientTS(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeClientTSHash(w http.ResponseWriter, _ *http.Request)
- func (r *Router) ServeDocs(opts ...DocOpt)
- func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (r *Router) SetLogger(logger *slog.Logger)
- func (r *Router) SetOpenAPIOptions(opts OpenAPIOptions)
- func (r *Router) SetTypeOverrides(overrides map[string]TypeOverride)
- func (r *Router) WriteClientJS(w io.Writer) error
- func (r *Router) WriteClientJSFile(path string) error
- func (r *Router) WriteClientJSHash(w io.Writer) error
- func (r *Router) WriteClientPY(w io.Writer) error
- func (r *Router) WriteClientPYFile(path string) error
- func (r *Router) WriteClientPYHash(w io.Writer) error
- func (r *Router) WriteClientTS(w io.Writer) error
- func (r *Router) WriteClientTSFile(path string) error
- func (r *Router) WriteClientTSHash(w io.Writer) error
- func (r *Router) WriteOpenAPIFile(path string) error
- type ServeAllDocsOpt
- type ServeAllDocsOptions
- type TypeOverride
- type TypedHandler
- type TypedHandlerFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cors ¶
func Cors(opts ...CORSOption) func(http.Handler) http.Handler
Cors returns a middleware that applies CORS headers.
func DefaultDocsHTML ¶
DefaultDocsHTML returns the integrated docs/admin UI HTML.
func Optional ¶ added in v0.0.25
Optional marks a typed request body as optional in generated OpenAPI and SDKs.
Usage:
- Optional[MyRequest]()
- Optional(MyRequest{})
func WriteDocsHTMLFile ¶
WriteDocsHTMLFile writes the default docs HTML to the path provided.
Types ¶
type CORSOption ¶
type CORSOption func(*CORSOptions)
CORSOption mutates CORSOptions.
func WithAllowCredentials ¶
func WithAllowCredentials(enabled bool) CORSOption
WithAllowCredentials toggles credential support.
func WithAllowedHeaders ¶
func WithAllowedHeaders(headers ...string) CORSOption
WithAllowedHeaders overrides the allowed headers list.
func WithAllowedMethods ¶
func WithAllowedMethods(methods ...string) CORSOption
WithAllowedMethods overrides the allowed methods list.
func WithAllowedOrigins ¶
func WithAllowedOrigins(origins ...string) CORSOption
WithAllowedOrigins overrides the allowed origins list.
func WithExposedHeaders ¶
func WithExposedHeaders(headers ...string) CORSOption
WithExposedHeaders overrides the exposed headers list.
func WithMaxAgeSeconds ¶
func WithMaxAgeSeconds(seconds int) CORSOption
WithMaxAgeSeconds sets the preflight cache duration.
type CORSOptions ¶
type CORSOptions struct {
AllowedOrigins []string
AllowedMethods []string
AllowedHeaders []string
ExposedHeaders []string
AllowCredentials bool
MaxAgeSeconds int
}
CORSOptions configures CORS middleware behavior.
type DocOpt ¶
type DocOpt func(*DocsOptions)
DocOpt mutates DocsOptions.
func WithDocsFile ¶
WithDocsFile overrides the docs HTML file path.
func WithDocsPath ¶
WithDocsPath overrides the docs base path.
func WithOpenAPIFile ¶
WithOpenAPIFile overrides the OpenAPI spec file path.
func WithOpenAPIPath ¶
WithOpenAPIPath overrides the OpenAPI route path.
func WithSQLRoot ¶ added in v0.0.24
WithSQLRoot sets the root folder scanned for db/sql schema and query files.
type DocsOptions ¶
type DocsOptions struct {
DocsPath string
DocsFile string
OpenAPIPath string
OpenAPIFile string
SQLRoot string
}
DocsOptions configures docs and OpenAPI routes.
type HandlerMeta ¶
type HandlerMeta struct {
Service string
Method string
Summary string
Description string
Tags []string
Responses []ResponseSpec
}
HandlerMeta provides optional documentation metadata for a handler.
type NoResponse200 ¶
type NoResponse200 struct{}
NoResponse200 indicates an explicit 200 with no body.
type NoResponse204 ¶
type NoResponse204 struct{}
NoResponse204 indicates an explicit 204 with no body.
type NoResponse500 ¶
type NoResponse500 struct{}
NoResponse500 indicates an explicit 500 with no body.
type OpenAPIContact ¶
OpenAPIContact provides contact info for the API.
type OpenAPIExternalDocs ¶
type OpenAPIExternalDocs struct {
Description string `json:"description,omitempty"`
URL string `json:"url"`
}
OpenAPIExternalDocs provides a link to external documentation.
type OpenAPILicense ¶
OpenAPILicense provides license info for the API.
type OpenAPIOptions ¶
type OpenAPIOptions struct {
Title string
Version string
Description string
Servers []OpenAPIServer
Tags []OpenAPITag
Contact *OpenAPIContact
License *OpenAPILicense
ExternalDocs *OpenAPIExternalDocs
}
OpenAPIOptions controls top-level OpenAPI document metadata.
type OpenAPIServer ¶
OpenAPIServer describes a server entry in the OpenAPI document.
type OpenAPITag ¶
OpenAPITag describes a top-level OpenAPI tag.
type ResponseSpec ¶ added in v0.0.25
ResponseSpec describes an explicit response contract for a typed route.
type Route ¶
type Route struct {
Pattern string
Method string
Path string
PathParams []string
Meta HandlerMeta
Guards []GuardSpec
Handler TypedHandler
}
Route captures a registered handler and its documentation metadata.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router registers routes and exposes documentation metadata.
func (*Router) AttachLogger ¶ added in v0.0.24
AttachLogger wraps next with request-event capture for docs live logging.
Call this once at the top-level mux/handler boundary for all-or-nothing logging. If next is nil, the router itself is wrapped.
func (*Router) Handle ¶
Handle registers a handler for the pattern. If the handler is not typed, the route is skipped for docs/client output.
func (*Router) HandleFunc ¶
func (*Router) HandleTyped ¶
func (r *Router) HandleTyped(pattern string, h TypedHandler, guards ...Guard)
HandleTyped registers a typed handler for the pattern.
func (*Router) ServeAllDocs ¶
func (r *Router) ServeAllDocs(opts ...ServeAllDocsOpt)
ServeAllDocs registers docs, OpenAPI, and client routes on the router.
func (*Router) ServeClientJS ¶
func (r *Router) ServeClientJS(w http.ResponseWriter, _ *http.Request)
ServeClientJS writes a generated JS client as an HTTP response.
func (*Router) ServeClientJSHash ¶
func (r *Router) ServeClientJSHash(w http.ResponseWriter, _ *http.Request)
ServeClientJSHash writes the hash of the JS client as an HTTP response.
func (*Router) ServeClientPY ¶
func (r *Router) ServeClientPY(w http.ResponseWriter, _ *http.Request)
ServeClientPY writes a generated Python client as an HTTP response.
func (*Router) ServeClientPYHash ¶
func (r *Router) ServeClientPYHash(w http.ResponseWriter, _ *http.Request)
ServeClientPYHash writes the hash of the Python client as an HTTP response.
func (*Router) ServeClientTS ¶
func (r *Router) ServeClientTS(w http.ResponseWriter, _ *http.Request)
ServeClientTS writes a generated TS client as an HTTP response.
func (*Router) ServeClientTSHash ¶
func (r *Router) ServeClientTSHash(w http.ResponseWriter, _ *http.Request)
ServeClientTSHash writes the hash of the TS client as an HTTP response.
func (*Router) ServeHTTP ¶
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP implements http.Handler.
func (*Router) SetOpenAPIOptions ¶
func (r *Router) SetOpenAPIOptions(opts OpenAPIOptions)
SetOpenAPIOptions replaces the OpenAPI document settings.
func (*Router) SetTypeOverrides ¶
func (r *Router) SetTypeOverrides(overrides map[string]TypeOverride)
SetTypeOverrides replaces the current type overrides used for client and OpenAPI generation.
func (*Router) WriteClientJS ¶
WriteClientJS writes a generated JS client to w.
func (*Router) WriteClientJSFile ¶
WriteClientJSFile writes a generated JS client to the file at path.
func (*Router) WriteClientJSHash ¶
WriteClientJSHash writes the hash of the JS client output to w.
func (*Router) WriteClientPY ¶
WriteClientPY writes a generated Python client to w.
func (*Router) WriteClientPYFile ¶
WriteClientPYFile writes a generated Python client to the file at path.
func (*Router) WriteClientPYHash ¶
WriteClientPYHash writes the hash of the Python client output to w.
func (*Router) WriteClientTS ¶
WriteClientTS writes a generated TS client to w.
func (*Router) WriteClientTSFile ¶
WriteClientTSFile writes a generated TS client to the file at path.
func (*Router) WriteClientTSHash ¶
WriteClientTSHash writes the hash of the TS client output to w.
func (*Router) WriteOpenAPIFile ¶
WriteOpenAPIFile writes the OpenAPI JSON output to the file at path.
type ServeAllDocsOpt ¶
type ServeAllDocsOpt func(*ServeAllDocsOptions)
ServeAllDocsOpt mutates ServeAllDocsOptions.
func WithClientJSPath ¶
func WithClientJSPath(path string) ServeAllDocsOpt
WithClientJSPath overrides the JS client route path.
func WithClientPYPath ¶
func WithClientPYPath(path string) ServeAllDocsOpt
WithClientPYPath overrides the Python client route path.
func WithClientTSPath ¶
func WithClientTSPath(path string) ServeAllDocsOpt
WithClientTSPath overrides the TS client route path.
func WithDocsOptions ¶
func WithDocsOptions(opts ...DocOpt) ServeAllDocsOpt
WithDocsOptions applies options for docs/OpenAPI routes.
func WithoutDocs ¶
func WithoutDocs() ServeAllDocsOpt
WithoutDocs disables docs/OpenAPI route registration.
type ServeAllDocsOptions ¶
type ServeAllDocsOptions struct {
DocsEnabled bool
DocsOptions []DocOpt
ClientJSPath string
ClientTSPath string
ClientPYPath string
}
ServeAllDocsOptions configures ServeAllDocs behavior.
type TypeOverride ¶
type TypeOverride = schema.TypeOverride
TypeOverride customizes how a Go type is rendered for clients and OpenAPI.
type TypedHandler ¶
type TypedHandler interface {
http.Handler
RequestType() any
ResponseType() any
Metadata() HandlerMeta
}
TypedHandler is an http.Handler with type metadata.
func Wrap ¶
func Wrap(handler http.Handler, req any, resp any, meta HandlerMeta) TypedHandler
Wrap creates a TypedHandler from a standard http.Handler and metadata.
func WrapFunc ¶
func WrapFunc(handler func(http.ResponseWriter, *http.Request), req any, resp any, meta HandlerMeta) TypedHandler
WrapFunc creates a TypedHandler from a handler function and metadata.
type TypedHandlerFunc ¶
type TypedHandlerFunc struct {
Handler func(http.ResponseWriter, *http.Request)
Req any
Resp any
Meta HandlerMeta
}
TypedHandlerFunc is a convenience wrapper for typed handler functions.
func (TypedHandlerFunc) Metadata ¶
func (t TypedHandlerFunc) Metadata() HandlerMeta
func (TypedHandlerFunc) RequestType ¶
func (t TypedHandlerFunc) RequestType() any
func (TypedHandlerFunc) ResponseType ¶
func (t TypedHandlerFunc) ResponseType() any
func (TypedHandlerFunc) ServeHTTP ¶
func (t TypedHandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)
Source Files