The Stainless SDK Generator

I worked on this extensively inside Azure and I know it is not an easy problem (and with more JSON Schema coming in 3.1/4.0, it is only getting harder). There are a lot of API patterns that you want to expose purpose built client abstractions for. Pagination is a big example. If you stick to OpenAPI, you have to ensure your specs use the patterns your client generator recognizes, and it's not always trivial for authors to know how to express that pattern and for your codegen to infer that pattern. In Azure we tended to rely more on custom extensions to OpenAPI because it made the contract a lot clearer and less error prone, but then you lose interoperability.

One thing to consider - I work on TypeSpec[1], and one of the main reasons we built it is to allow encapsulation and reuse of patterns in a first-class way. So, rather than the contract being "endpoints which declare parameters and/or return types with these shapes are inferred to be paginated endpoints", the contract can be "use Page" and the emitted OpenAPI conforms to the contract without effort. It would be fun to see a Stainless TypeSpec library for all the patterns your codegen supports!

1: https://typespec.io

Generated code has a bad rap for results that are not idiomatic or user-friendly, but I think it's clear that it doesn't have to be that way—getting it right just takes a lot of care and effort that is typically overlooked.

Stainless is definitely best-in-class here as far as I've seen.

I agree, I love them in theory, but wrangling mustache templates is a hassle. They end up super coupled to the code that populates them which makes them a bear to modify.

From what I've seen, a lot of API developers find that openapi-generator flat-out breaks or produces broken code for their OpenAPI spec (varies language-to-language of course).

Beyond hitting the "it just works" mark more often, some other key differentiators:

1. much easier to configure & customize

2. auto-retry with exponential backoff (this is huge for our customers)

3. auto-pagination

4. overall ergonomics of using the SDK

5. internals that look handwritten (some people care, others don't)

6. one-click releases to github & package managers w/ semver, changelogs, etc

7. careful handling of edge cases (eg, will adding a new enum variant cause your Java client to crash?)

8. a long tail of more advanced features, like webhook signature verification, streaming, etc

Thanks for the question – hope this helps :)

On the other hand, a benefit of a more complete API is that in typed languages you can tab-complete your way to success. With each endpoint a function and all the requisite configuration (API URL, etc.) bundled in, for basic integrations you may never even have to reference documentation, or if you do, very little of it, as your IDE finds functions/properties for you and you can read documentation right out their docstrings.