Documentation
¶
Overview ¶
Package routecontracts registers HTTP routes and OpenAPI operations together.
It is intentionally router-neutral and uses only the common method registration shape already provided by ports.HTTPRouter. PATCH support is detected with a local optional interface so stable router interfaces are not widened.
Registered routes automatically attach bounded routepolicy observability labels to the request context so outer metrics and request logging middleware can record policy shape without seeing raw scopes, tenants, or policy names.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/routecontracts`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Package routecontracts keeps runtime route registration and OpenAPI operation registration in one place.
Index ¶
- type CoverageError
- type Options
- type Policy
- type PolicyFunc
- type Registry
- func (registry *Registry) Delete(pattern string, operation specs.Operation, handler http.Handler, ...) error
- func (registry *Registry) Get(pattern string, operation specs.Operation, handler http.Handler, ...) error
- func (registry *Registry) Patch(pattern string, operation specs.Operation, handler http.Handler, ...) error
- func (registry *Registry) Post(pattern string, operation specs.Operation, handler http.Handler, ...) error
- func (registry *Registry) Put(pattern string, operation specs.Operation, handler http.Handler, ...) error
- func (registry *Registry) Register(route Route) error
- func (registry *Registry) Routes() []Route
- func (registry *Registry) Validate() error
- type Route
- type Router
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CoverageError ¶
type CoverageError struct {
Problems []string
}
CoverageError describes a route-contract coverage problem.
func (CoverageError) Error ¶
func (err CoverageError) Error() string
Error returns a human-readable error.
type Policy ¶
type Policy interface {
Apply(specs.Operation) (specs.Operation, []func(http.Handler) http.Handler, error)
}
Policy derives automatic middleware and operation metadata from a route operation.
type PolicyFunc ¶
PolicyFunc adapts a function to Policy.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry registers runtime routes and matching OpenAPI operations.
func NewRegistry ¶
NewRegistry constructs a registry with default behavior.
func NewRegistryWithOptions ¶
NewRegistryWithOptions constructs a registry with policy options.
func (*Registry) Delete ¶
func (registry *Registry) Delete(pattern string, operation specs.Operation, handler http.Handler, middleware ...func(http.Handler) http.Handler) error
Delete registers a DELETE route.
func (*Registry) Get ¶
func (registry *Registry) Get(pattern string, operation specs.Operation, handler http.Handler, middleware ...func(http.Handler) http.Handler) error
Get registers a GET route.
Example ¶
package main
import (
"fmt"
"net/http"
"github.com/aatuh/api-toolkit/v4/routecontracts"
"github.com/aatuh/api-toolkit/v4/specs"
)
type exampleRouteRouter struct {
calls []string
}
func (r *exampleRouteRouter) Get(pattern string, _ http.HandlerFunc) {
r.calls = append(r.calls, http.MethodGet+" "+pattern)
}
func (r *exampleRouteRouter) Post(pattern string, _ http.HandlerFunc) {
r.calls = append(r.calls, http.MethodPost+" "+pattern)
}
func (r *exampleRouteRouter) Put(pattern string, _ http.HandlerFunc) {
r.calls = append(r.calls, http.MethodPut+" "+pattern)
}
func (r *exampleRouteRouter) Delete(pattern string, _ http.HandlerFunc) {
r.calls = append(r.calls, http.MethodDelete+" "+pattern)
}
func main() {
router := &exampleRouteRouter{}
openapi := specs.NewRegistry(specs.Info{Title: "Widget API", Version: "1.0.0"})
registry := routecontracts.NewRegistry(router, openapi)
if err := registry.Get("/widgets", specs.Operation{
OperationID: "listWidgets",
Responses: map[int]specs.Response{http.StatusOK: {Description: "OK"}},
}, http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})); err != nil {
panic(err)
}
fmt.Println(router.calls[0])
}
Output: GET /widgets
func (*Registry) Patch ¶
func (registry *Registry) Patch(pattern string, operation specs.Operation, handler http.Handler, middleware ...func(http.Handler) http.Handler) error
Patch registers a PATCH route when the router supports Patch.
func (*Registry) Post ¶
func (registry *Registry) Post(pattern string, operation specs.Operation, handler http.Handler, middleware ...func(http.Handler) http.Handler) error
Post registers a POST route.
func (*Registry) Put ¶
func (registry *Registry) Put(pattern string, operation specs.Operation, handler http.Handler, middleware ...func(http.Handler) http.Handler) error
Put registers a PUT route.
type Route ¶
type Route struct {
Method string
Pattern string
Handler http.Handler
Middleware []func(http.Handler) http.Handler
Operation specs.Operation
}
Route binds an HTTP route to its OpenAPI operation.
type Router ¶
type Router interface {
Get(pattern string, h http.HandlerFunc)
Post(pattern string, h http.HandlerFunc)
Put(pattern string, h http.HandlerFunc)
Delete(pattern string, h http.HandlerFunc)
}
Router is the minimal router contract used by Registry.
Source Files