There's no winning at this layer and every attempt is as doomed as medieval alchemists trying to transmute lead to gold.
The key here is overall speed, but you can't trade the time spent learning/understanding the API contract for these crazy complicated tools. The developer still has to look at the operations and data models exposed by the API, understand them, amd plan for how to integrate them into the larger application.
The big bonus of the human documentation approaches today is that time is somewhat combined with building the client. The downside of course is that it's a human doing it. My point here is that you can't take the time a human is going to spend understanding the API concepts and then tack on a bunch of time learning, configuring, and running the client gen code and associated infrastructure as well and expext that your solution is going to win.
The more complicated these codegen setups get, the less comicated just reading some docs and spinning up a few lines of client code is. And guess which I'm going to choose as a dev? Whatever is overall fastest and gets me on to the problems I'm really trying to solve.
Speaking personally as a full stack engineer, unless the backend is completely trivial to implement I find it much faster and more efficient to write and iterate JSON schema while implementing frontend features than actually implement backend logic first.
> The big bonus of the human documentation approaches today is that time is somewhat combined with building the client.
This is wild to me; human documentation is absurdly error-prone and it's almost always and immediately out of date. (Zod or other DSL) -> OpenAPI -> generated docs (and types! and clients! and mocks!) are always going to be better; always accurate, and faster. The upfront cost is slightly higher, but the ROI is _significant_.
OpenAPI specs lend themselves to excellent docs, ala Mintify or Docusaurus. Even interactive ones, like Swagger UI. The vast majority of API browsers & tooling understands OAPI, so why re-create (an often incomplete) version of the truth when using those tools?
> Whatever is overall fastest and gets me on to the problems I'm really trying to solve.
You may start (slightly) faster, but you'll incur significant cost when you move past the "trivial implementation" stage.
For instance:
- Do you do request & response validation on the server? That'll often need duplication on the client (e.g, error messages, and once out of sync, client-side validation mismatches server-side response)
- Typescript on client & server? Then you're already doing the manual work (often more than once) that oAPI->types would get you for free.
- Implementing client-side XHR calls manually, and getting typing right, is a pretty significant undertaking. Multiply that by the number of client-side stacks the API will be consumed by. Or, just generate them via OAPI (or real-time infer via something like ts-rest)
- TS on client, but another BE stack? OpenAPI, when used right, ensures the "contract" is 1:1. When BE changes, client needs changing -- or it breaks. You want this safety.
- Manually mocking API responses is wasteful; write good oAPI specs and auto-generate mocks (e.g, MSW).
- Do you test the real API implementation? OpenAPI specs can help you do that automatically.
At this stage of my career, I would turn down a job offer from a company/team that wasn't willing to use OpenAPI or equivalent single-source-of-truth (*unless I'm in a truly desperate situation)
The key here is overall speed, but you can't trade the time spent learning/understanding the API contract for these crazy complicated tools. The developer still has to look at the operations and data models exposed by the API, understand them, amd plan for how to integrate them into the larger application.
The big bonus of the human documentation approaches today is that time is somewhat combined with building the client. The downside of course is that it's a human doing it. My point here is that you can't take the time a human is going to spend understanding the API concepts and then tack on a bunch of time learning, configuring, and running the client gen code and associated infrastructure as well and expext that your solution is going to win.
The more complicated these codegen setups get, the less comicated just reading some docs and spinning up a few lines of client code is. And guess which I'm going to choose as a dev? Whatever is overall fastest and gets me on to the problems I'm really trying to solve.