api

Documentation

Index

• func RegisterDocsHandler(router chi.Router, specURL string)
• func SetupAPI(router chi.Router, cfg config.APIConfig, tokenStore auth.TokenStore, ...) (huma.API, error)
• func SetupHTML(router chi.Router, cfg HTMLServerConfig) error
• type HTMLServerConfig
• type ServerConfig

Functions

func RegisterDocsHandler

func RegisterDocsHandler(router chi.Router, specURL string)

RegisterDocsHandler registers the Scalar UI documentation handler at /api/docs. Scalar UI is embedded directly in the binary — no CDN dependency, consistent with the single-binary deployment philosophy.

The specURL parameter is the URL path where the OpenAPI spec is served, typically "/api/openapi.json". Scalar UI will fetch this URL from the browser to render the interactive documentation.

Huma's built-in docs handler (Stoplight Elements via CDN) is disabled in SetupAPI by setting DocsPath to "". This handler replaces it with a self-hosted Scalar UI that works offline and air-gapped environments.

func SetupAPI

func SetupAPI(
	router chi.Router,
	cfg config.APIConfig,
	tokenStore auth.TokenStore,
	apiKeyStore auth.APIKeyStore,
	recoveryMiddleware func(http.Handler) http.Handler,
	registerRoutes func(api huma.API),
) (huma.API, error)

SetupAPI creates a Huma API instance on the provided Chi router, wires all middleware in the correct order, then calls registerRoutes to register every generated resource endpoint.

Middleware order (per security and operational best-practices):

1. Chi-level: RealIP — extract real client IP before any processing
2. Chi-level: Logger — log every request with final status code
3. Chi-level: Recovery (gen/middleware) — catch panics before they terminate the process
4. Huma-level: CORS — set cross-origin headers before auth check
5. Huma-level: RateLimit — enforce rate limits before expensive auth lookup
6. Huma-level: Auth — validate bearer tokens / API keys

After all middleware is wired, SetupAPI calls registerRoutes (i.e. genapi.RegisterAllRoutes) to register all generated CRUD endpoints. Huma automatically serves the OpenAPI spec at /api/openapi.json and /api/openapi.yaml because OpenAPIPath is set to "/api/openapi". The Scalar UI docs handler must be registered separately via RegisterDocsHandler.

Example wiring in a generated project's main.go:

api, err := apiserver.SetupAPI(router, cfg.API, tokenStore, apiKeyStore, gen_middleware.Recovery, genapi.RegisterAllRoutes)

func SetupHTML

func SetupHTML(router chi.Router, cfg HTMLServerConfig) error

SetupHTML wires session middleware and HTML route groups onto a Chi router.

Route group structure:

1. Session LoadAndSave middleware wraps ALL routes (including auth routes) so that the OAuth callback handler can commit sessions after login. This is critical — if LoadAndSave only wraps the protected group, the OAuth callback (which lives in the public group) cannot write session data. (Pitfall 9: Session LoadAndSave must wrap ALL routes including auth routes)

2. Public group (no auth required): intended for OAuth callback routes, /auth/login, /auth/logout, and any other unauthenticated pages. These must be registered BEFORE the protected RequireSession group to avoid infinite redirect loops. (Pitfall 4: OAuth callback routes must be outside RequireSession group)

3. Protected group (RequireSession enforced): resource HTML routes live here. cfg.RegisterRoutes is called on this group so every resource route automatically inherits session auth without each handler checking itself.

Example wiring in a generated project's main.go:

err := apiserver.SetupHTML(router, api.HTMLServerConfig{
    SessionManager: sm,
    RegisterRoutes: genhtml.RegisterAllHTMLRoutes,
})

Types

type HTMLServerConfig

type HTMLServerConfig struct {
	// SessionManager is the SCS session manager used for LoadAndSave middleware
	// and RequireSession auth enforcement.
	SessionManager *scs.SessionManager

	// RegisterRoutes is an optional function that registers resource HTML routes
	// on a chi.Router group. When RequireAuth is true, the group enforces
	// session authentication. Pass nil if you only need the session middleware
	// wired without any routes.
	RegisterRoutes func(chi.Router)

	// RequireAuth controls whether HTML routes are protected by RequireSession
	// middleware. When false (default), routes are publicly accessible — suitable
	// for freshly generated projects before auth is configured. Set to true once
	// OAuth or password login routes are wired up.
	RequireAuth bool

	// RegisterPublicRoutes is an optional function that registers routes in the
	// public (unauthenticated) group. Auth routes (login, logout, OAuth callbacks)
	// are registered here to avoid RequireSession redirect loops.
	RegisterPublicRoutes func(chi.Router)
}

HTMLServerConfig holds the dependencies required to set up HTML (browser-facing) routes. It separates session management from route registration so that the forge framework layer never needs to import generated application code.

type ServerConfig

type ServerConfig struct {
	APIConfig   config.APIConfig
	TokenStore  auth.TokenStore
	APIKeyStore auth.APIKeyStore
}

ServerConfig groups the configuration dependencies needed to set up the API server. This is a convenience struct for applications that assemble the server from a single configuration object rather than passing each dependency individually.