Documentation
¶
Overview ¶
Package rest provides a transport-agnostic REST API builder for go-codex.
Define routes with codec-backed request and response types; the builder returns a RouteHandle with typed Decode and Encode helpers. Pass those helpers to any HTTP framework (net/http, Gin, Chi, Echo) — this package does not import net/http or any framework.
Spec generation is also available: Builder.OpenAPISpec derives a complete OpenAPI 3.1 document from the registered routes.
Typical usage:
b := rest.NewBuilder(rest.Info{Title: "User API", Version: "1.0.0"})
b.AddServer("production", rest.Server{URL: "https://api.example.com"})
createUser := rest.AddRoute[CreateUserReq, User](b, "POST", "/users",
createUserCodec, userCodec, rest.RouteConfig{
OperationID: "createUser",
Summary: "Create a user",
ReqSchemaName: "CreateUserRequest",
RespSchemaName: "User",
})
// In your HTTP handler (any framework):
req, err := createUser.Decode(body) // JSON → CreateUserReq, validates
user, err := myService.CreateUser(req)
out, err := createUser.Encode(user) // User → JSON
// OpenAPI 3.1 spec:
doc, err := b.OpenAPISpec()
yaml, _ := doc.MarshalYAML()
Encoding is JSON only. AddRoute uses format.JSON internally; for other formats construct a format.Format directly and call its Unmarshal/Marshal.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates route registrations and produces OpenAPI specs. Create one with NewBuilder.
func NewBuilder ¶
NewBuilder returns a Builder initialised with the given API metadata.
func (*Builder) AddSchema ¶
AddSchema registers a named schema in components/schemas. Use this to register reusable schemas (e.g. shared error types) that are referenced by SchemaName in route configs but not inlined in any codec.
type Info ¶
Info is an alias for openapi.Info. Using the alias avoids duplicating fields and keeps the two in sync automatically.
type Param ¶
Param is an alias for route.Param so callers do not need to import route just to specify path or query parameters.
type ResponseMeta ¶
type ResponseMeta struct {
Status string // e.g. "400", "404", "default"
Description string
Schema *schema.Schema // nil for description-only responses (e.g. 404)
SchemaName string // non-empty → $ref in spec
}
ResponseMeta describes one additional response entry for a route (errors, redirects, etc.). The primary success response is derived from the response codec and RespStatus/RespDescription/RespSchemaName in RouteConfig.
type RouteConfig ¶
type RouteConfig struct {
OperationID string
Summary string
Description string
Tags []string
// PathParams and QueryParams are included in the OpenAPI spec as path/query
// parameters. Codec-based path/query decoding is a future extension.
PathParams []route.Param
QueryParams []route.Param
// ReqSchemaName, when non-empty, emits a $ref for the request body schema
// in the spec and registers the schema under that name in components/schemas.
ReqSchemaName string
// RespStatus is the HTTP status code for the primary success response.
// Defaults to "201" for POST, "200" for all other methods.
RespStatus string
// RespDescription is the description for the primary success response.
RespDescription string
// RespSchemaName, when non-empty, emits a $ref for the response schema.
RespSchemaName string
// Responses are additional response entries (error codes, etc.) appended
// after the primary success response in the spec.
Responses []ResponseMeta
}
RouteConfig holds metadata for a route registration. It controls both spec output and default behaviour of the returned RouteHandle.
type RouteHandle ¶
type RouteHandle[Req, Resp any] struct { // Descriptor is the frozen route.Route built at registration time. // Use it to inspect method, path, parameters, and spec metadata. Descriptor route.Route // Decode deserialises and validates a JSON request body into Req. // All Refine constraints on the request codec run automatically. Decode func(body []byte) (Req, error) // Encode serialises Resp to JSON bytes. Encode func(resp Resp) ([]byte, error) }
RouteHandle is returned by AddRoute. It holds the frozen spec descriptor and codec-backed Decode/Encode helpers.
Decode and Encode use JSON encoding. For body-less methods (GET, HEAD, DELETE), Decode can still be called if the request carries a body, but typical REST usage will not call it.
func AddRoute ¶
func AddRoute[Req, Resp any]( b *Builder, method, path string, reqCodec codex.Codec[Req], respCodec codex.Codec[Resp], config RouteConfig, ) *RouteHandle[Req, Resp]
AddRoute registers a route with the builder and returns a RouteHandle.
reqCodec is used to decode and validate the JSON request body. respCodec is used to encode the JSON response.
AddRoute is a free function (not a method) because Go requires type parameters to appear on free functions, not on method receivers.
The descriptor is built and frozen at call time; later mutations to config do not affect the registered route or the returned handle.
Source Files