Schema-driven codegen
Write the interface once as a machine-readable schema, then generate the code that implements or
consumes it — clients, server stubs, docs, tests — instead of hand-writing each one. The schema becomes
the single source of truth; everything downstream is a projection of it. protoc is the archetype;
OpenAPI Generator is the same move applied to REST, at a scale that makes the
argument visible: 50+ client and 40+ server generators, plus MySQL schemas, Postman collections,
JMeter plans, and WSDL, all falling out of one spec openapi-generator-docs.
The trade
What you buy is the elimination of drift: N hand-written clients against one API will disagree, and the disagreement surfaces in production. The one-line version — “You should not have to rebuild the same API client for every language” — is really a claim about consistency, not typing speed.
What you pay is a template layer between you and your own code. The generated client is only as good as the generator for your language, and the OpenAPI Generator table makes that spread concrete: Java has ~15 maintained HTTP-client variants; other targets have one, of unstated quality. A count of generators measures reach, not depth. The escape hatch is that templates are Mustache and forkable, which pushes the fix onto you.
Who does the specializing?
This lands next to the spoke’s other codegen source and sharpens a question the synthesis already
raised. clickhouse-rowbinary was described there as not a protoc-style schema compiler: instead of
a generator emitting code, it ships densely-commented primitives plus a SKILL.md so an LLM agent
writes the type-specialized parser. OpenAPI Generator is the thing that framing was
defined against — the classic, deterministic, template-driven schema compiler, 26.5k stars and eight years
in.
So the spoke now holds both poles of “who compiles the toolchain”:
- Generator writes the code (OpenAPI Generator): deterministic, reviewable, reproducible in CI, versioned. Bounded by which targets someone maintained a template for.
- Agent writes the code (ClickHouse RowBinary +
SKILL.md): unbounded targets, no template to maintain, at the cost of determinism and repeatability.
Both start from the same premise — a human should not hand-write the boilerplate that a machine-readable contract already implies. They disagree about what kind of machine reads the contract — and which way new tooling in this corner falls is the open question the synthesis now tracks.
Related
openapi-generator · clickhouse-rowbinary · monomorphization · openapi-generator-docs · openapi-generator-post · developer-tooling · synthesis