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
(paged 2026-08-14 as protocol-buffers, with grpc as the service half);
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 archetype turns out to be the narrower one (added 2026-08-14). protoc generates message
classes for about ten languages and nothing else; everything beyond that is a plugin, which is how
grpc bolts service stubs onto the same compiler without Protobuf knowing what an RPC is. OpenAPI
Generator ships the breadth in the box. So the two poles of this technique differ on where the
extension point sits — a plugin API versus a Mustache template — and Protobuf's answer scales to
things its authors never contemplated, at the cost of making you write a compiler plugin to get
there.
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 · protocol-buffers · grpc · developer-tooling · synthesis