Codegen Server Stubs vs Client SDKs
Quick answer: One OpenAPI spec can generate both a client SDK and a server stub, and they point in opposite directions. The client SDK turns local method calls into outgoing HTTP requests and parses the responses. The server stub registers the routes, binds incoming requests, and routes them to handler methods that you fill in with real logic. The client is close to a finished product; the server stub is a skeleton that guarantees the interface shape but not the behavior.
One spec, two directions
The same description drives both sides, but the work is mirrored. On the client, the generator builds request serialization, response parsing, authentication, and error handling so callers never touch raw HTTP. On the server, it generates the route wiring, request deserialization, parameter validation, and response serialization, and leaves the business logic to you. The client makes the remote API feel local; the stub makes a new endpoint conform to the contract from the first request.
What each side owns
| Dimension | Client SDK | Server stub |
|---|---|---|
| Direction | Method call to HTTP request | HTTP request to handler |
| Handles | Serialization, auth, retries | Routing, binding, validation |
| Generated state | Near-complete, ready to call | Skeleton with empty handlers |
| Your work | Wrappers, error mapping | All business logic |
| Output | A library consumers import | Framework code you run |
The server stub is a skeleton
A generated stub does not implement the endpoint. Its handler methods are abstract or throw until you replace them, and everything outside the spec, such as middleware, persistence, and authorization rules, is still yours to write. When the spec changes and you regenerate, the generator has to preserve the logic you added, usually through protected regions or by keeping generated code separate from hand-written files. Editing the generated output directly risks losing that work on the next build.
Verifying the two sides line up
Generating both ends from one spec does not prove they agree at runtime. Point the generated client at the running stub or its real implementation and run an ordered scenario that exercises each operation, so the requests the client sends match the shapes the server expects; Powerduck can drive that scenario and assert the status and response fields, catching a mismatch in types or naming before either side ships.
You do not have to generate both
Generating both sides is an option, not a requirement, and many teams only need one. An internal microservice might generate the server stub so every service follows the same routing and validation, while the callers use clients they already own. A public API often does the reverse: the team maintains the server by hand and publishes generated client SDKs to cut the integration cost for external developers. The deciding factor is who bears the cost of staying aligned with the contract. If that burden sits on many consumers, generating clients pays off; if it sits inside one server team, the stub is the higher-value output.
Honest limits
Template quality is not symmetric across the two outputs, and server generators vary more between frameworks than client generators do. The stub covers only the interfaces the spec describes, so cross-cutting concerns and any endpoint outside the spec remain manual. The client faithfully reflects the contract but cannot verify the server behaves correctly, and the stub guarantees the wire shape while saying nothing about whether the logic inside is correct.
Frequently asked questions
Does the server stub implement my API? No. It wires the routes and leaves the handler bodies for you to fill in.
Can I edit the generated stub directly? Prefer protected regions or separate files, since regeneration can overwrite direct edits.
Are the two generated outputs equally mature? Often not. Server templates vary more across frameworks than client templates.
Does one spec guarantee the ends match? It aligns the shapes, but runtime agreement still needs end-to-end scenario checks.
The bottom line
A client SDK and a server stub are mirror images of the same spec: one turns calls into requests, the other routes requests into handlers you write. Treat the stub as a skeleton with protected edits, and verify the two sides against each other with real scenarios. For more on generated clients, see the OpenAPI codegen guide hub.