Documentation
¶
Overview ¶
Package client generates a TypeScript API client from an OpenAPI 3.1 document.
gombit client generate runs openapi-typescript for schema types and writes a thin openapi-fetch wrapper whose errors map to the D10 envelope.
gombit client check regenerates the sample spec and client in-process from SampleApp and fails when committed artifacts would change.
Index ¶
Constants ¶
const ( // SampleSpecPath is the committed OpenAPI fixture for the sample widget API. SampleSpecPath = "examples/client/openapi.json" // SampleOutDir is the committed TypeScript client generated from SampleSpecPath. SampleOutDir = "examples/client/frontend/src/api/generated" )
const ( // DefaultSpecPath is the conventional OpenAPI document path. DefaultSpecPath = "openapi.json" // DefaultOutDir is the conventional generated-client directory (design §23.3). DefaultOutDir = "frontend/src/api/generated" )
const TypedAPIPrefix = "/api/v1"
TypedAPIPrefix is D8 / DEFAULT_API_PREFIX. Scaffolded pages and the placeholder OpenAPI client use these path keys. gombit client generate rewrites live Huma paths to this prefix before openapi-typescript so `client.GET("/api/v1/...")` keeps typechecking after GOMBIT_API_PREFIX changes. rewriteAPIRequest maps them back to the live prefix on the wire.
Variables ¶
var ErrDrift = errors.New("client: contract drift")
ErrDrift is the error CheckDrift wraps when a committed artifact differs from what the contract produces.
Functions ¶
func CheckDrift ¶
func CheckDrift(ctx context.Context, opts DriftOptions) error
CheckDrift regenerates the OpenAPI document and TypeScript client and reports whether committed artifacts would change.
The spec is compared semantically via encoding/json, so whitespace-only differences are not drift. Generated TypeScript is compared byte-for-byte.
The document used for comparison comes from, in order: opts.SpecBytes (a pre-fetched live spec), opts.API (an in-process huma.API — this module's own tests and go:generate directive use this to compare examples/client/ against SampleApp), or SampleApp() itself. Generated apps have neither a Go-level huma.API nor a reason to compare against the framework's sample widget API, so the CLI's `gombit client check --url` path fetches the live spec over HTTP and passes it as SpecBytes.
When Write is true, fixtures are rewritten in place.
Types ¶
type DriftOptions ¶
type DriftOptions struct {
// WorkDir is the repository root. Empty means the current working directory.
WorkDir string
// SpecPath is the committed OpenAPI fixture, relative to WorkDir unless absolute.
// Default: SampleSpecPath.
SpecPath string
// OutDir is the committed generated-client directory, relative to WorkDir unless absolute.
// Default: SampleOutDir.
OutDir string
// API is the Huma API to emit. Nil and SpecBytes nil means SampleApp().
API huma.API
// SpecBytes is a pre-fetched OpenAPI document (e.g. from a live /openapi.json
// URL) to treat as the current contract. Takes precedence over API. Callers
// outside this module — generated apps have no Go-level huma.API to pass —
// use this to check their own contract instead of the framework's SampleApp.
SpecBytes []byte
// Write regenerates committed fixtures instead of comparing them.
Write bool
// NPXBinary is the npx executable used by Generate. Default: npx.
NPXBinary string
Stdout io.Writer
Stderr io.Writer
}
DriftOptions configures a contract drift check or fixture rewrite.
Source Files