exp/api/openapi: add oapi-codegen generated API client PoC

[AmariahAK]

Description

Closes #1998

@bwplotka @kakkoyun @vesari

---

i. What was the issue

The Prometheus HTTP API client at api/prometheus/v1/api.go is entirely hand-written (1,585 lines). Maintaining it manually creates ongoing overhead — fixing bugs, syncing with Prometheus API changes, and maintaining custom unsafe-based JSON decoders for performance. Prometheus now officially serves an OpenAPI 3.1/3.2 specification at /api/v1/openapi.yaml, opening the door to code generation. The question: can we replace or supplement the hand-written client with a generated one?

ii. Where was the issue

The hand-written client uses github.com/json-iterator/go with custom unsafe decoders for the hot-path types (SamplePair, SampleHistogramPair, SampleStream). A generated client would produce strict JSON-serializable Go structs using standard encoding/json, potentially losing both the convenient model.Value interface (Scalar/Vector/Matrix dispatch) and the optimized decoding performance.

iii. How we investigated

Built a proof-of-concept under exp/api/openapi/, following the existing exp/api/remote/ pattern for experimental modules.

Generated client:

• Created an OpenAPI 3.0.3 specification (spec.yaml, 1,055 lines) covering all 22 v1 API endpoints with proper response envelopes ({status, data, errorType, error, warnings, infos})
• Generated client + types (openapi.gen.go, 5,216 lines) using oapi-codegen v2.8.0
• Built a high-level wrapper (client.go) that dispatches resultType to model.Scalar/model.Vector/model.Matrix
• Also tested against the real Prometheus OpenAPI 3.1 golden spec (spec_real_31.yaml, 5,510 lines from openapi_3.1_golden.yaml), which generates 12,739 lines — compiles but produces ParseQueryResponse name collisions from shared GET/POST response types

Compatibility verified:

• Auth: ✅ RequestEditorFn for bearer tokens and custom headers
• HTTP client injection: ✅ WithHTTPClient for custom transport
• Response envelope: ✅ warnings/infos/errorType all handled
• Option pattern: ✅ QueryOptions struct with Timeout, LookbackDelta, Stats, Limit

Performance (Apple M1):

Scenario	Round-trip decode
Vector (100 series)	~89µs, 30KB, 819 allocs
Matrix (10×1000 datapoints)	~2.4ms, 234KB, 101 allocs
Histogram (10×100 datapoints)	~1.2ms, 327KB, 7,101 allocs

The overhead comes from double JSON encoding: json.Unmarshal into generated types → json.Marshal → json.Unmarshal into model.Value. Custom oapi-codegen templates could inject json-iterator for the hot path.

Tests:

• 8 unit tests covering scalar, vector, matrix, errors, label names, label values, warnings/infos propagation
• 3 decode benchmarks (vector, matrix, histogram)
• 21 existing root module tests continue to pass — zero breakage

iv. Why oapi-codegen over alternatives

Tool	Verdict
oapi-codegen	✅ Recommended — idiomatic Go, OpenAPI 3.0/3.1 support, template-customizable, Go-only toolchain (no JVM), active community
OpenAPI Generator	❌ Requires Java/Docker, produces less idiomatic Go (Java-style patterns), complex template customization (Mustache)
go-swagger	❌ Swagger 2.0 only — no OpenAPI 3.x support
gnostic	❌ Low-level protobuf-focused tool, not designed for developer-friendly HTTP clients

v. How to test locally

# Run the generated client tests
cd exp && go test ./api/openapi/ -v

# Run benchmarks
cd exp && go test ./api/openapi/ -bench=. -benchmem

# Verify no breakage to existing client
go test ./api/prometheus/v1/ -v -count=1

# Regenerate from spec
cd exp/api/openapi && oapi-codegen --config oapi-codegen.yaml spec.yaml

Key findings for the maintainers

1. oapi-codegen is viable. The generated code is idiomatic, compilable, and covers all endpoints.
2. model.Value retention requires a wrapper — the result field varies by resultType (array for scalar, array-of-objects for vector/matrix), which OpenAPI cannot express as a discriminated union. The wrapper round-trips through JSON to dispatch to the correct type.
3. Performance gap is measurable but narrowable — the double-encoding overhead is ~7K allocs for histogram results. Custom oapi-codegen templates injecting json-iterator for SamplePair/SampleHistogramPair could close most of this gap.
4. Real spec is 5× larger — the 5,510-line golden file generates 12,739 lines, with minor name collisions that are resolvable via oapi-codegen configuration.
5. Experimental module placement works — exp/api/openapi/ follows the same pattern as exp/api/remote/ and doesn't break the stable module.