ring:adopting-lib-commons-huma-wrapper

Adopt the lib-commons Huma OpenAPI Wrapper

When to use

• A Go service needs code-first OpenAPI 3.1 over Fiber (Huma) with RFC 9457 application/problem+json errors
• User asks to "adopt the lib-commons OpenAPI/problem wrapper", "use the shared Huma wrapper", "standardize error responses on RFC 9457"
• A service already carries a local copy of the wrapper (internal/shared/adapters/openapi, shared/openapi, shared/humaerr, a hand-rolled huma.NewError override) and should move onto the shared lib-commons/v5/commons/net/http/{openapi,problem}
• A service is still on swaggo/swag (Swagger 2.0) and is migrating to Huma

Skip when

• Service is not a Go project
• Task does not involve an HTTP API / OpenAPI spec
• The service genuinely needs a bespoke error envelope that is NOT RFC 9457 (rare; challenge it first)
• Documentation-only or non-code task

You orchestrate. Agents implement. NEVER use Edit/Write/Bash on Go source files — all code changes go through Task(subagent_type="ring:backend-go"). TDD mandatory for implementation gates (RED → GREEN → REFACTOR). The orchestrator owns git (commit/push/PR/release) and NEVER commits without the user's go-ahead.

Architecture

The wrapper is two packages in lib-commons/v5 (minimum v5.6.0):

Alias	Import Path	Purpose
openapi	github.com/LerianStudio/lib-commons/v5/commons/net/http/openapi	Config, New (builds the humafiber API), DeclareBearerAuth, ServeSpec
problem	github.com/LerianStudio/lib-commons/v5/commons/net/http/problem	Install (global huma.NewError override), MapError, Detail, BaseURI

openapi.New(app, group, cfg) constructs the Fiber-v2 Huma API via humafiber.NewV2WithGroup (the default humafiber.New targets Fiber v3 — wrong major), strips Transformers/OnAddOperation/CreateHooks, and clears the auto-mounted /openapi.json + /docs (auto-mount is a latent production exposure — the spec must be served explicitly and gated). Config{Title, Version, Description, Servers}.