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
- Variables
- func CheckDrift(ctx context.Context, opts DriftOptions) error
- func Generate(ctx context.Context, opts Options) error
- func GeneratedFiles() []string
- func SampleApp() (*framework.App, error)
- func SpecEqual(committed, current []byte) (bool, error)
- type DriftOptions
- type DriftedFile
- type Options
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.
var ErrNotGenerated = errors.New("not generated by gombit")
ErrNotGenerated is the error Generate wraps when it refuses, before writing anything, to overwrite a file of the output directory that gombit did not generate (no generated banner) without Force.
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.
func GeneratedFiles ¶ added in v0.8.0
func GeneratedFiles() []string
GeneratedFiles are the files of a generated client directory that Generate writes and the drift check compares: the only ones gombit owns there.
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.
type DriftedFile ¶ added in v0.8.0
type DriftedFile struct {
// Path is as given (SpecPath, or OutDir joined with the file name).
Path string `json:"path"`
Spec bool `json:"spec,omitempty"`
// Missing is a generated client file that is not committed at all.
Missing bool `json:"missing,omitempty"`
}
DriftedFile is a committed contract artifact that differs from what the contract produces: the OpenAPI document (Spec) or a generated client file.
func ClientDrift ¶ added in v0.8.0
func ClientDrift(ctx context.Context, opts DriftOptions) ([]DriftedFile, error)
ClientDrift reports the generated client files in opts.OutDir that differ from what opts.SpecBytes generates, by the comparison CheckDrift fails on (byte for byte; a file that is not there is Missing). Only the client is compared: opts.SpecPath is not read, and the document is the caller's to compare (SpecEqual). It writes nothing outside a temporary directory; Write and API are ignored.
Source Files