Show HN: Turn OpenAPI to Universal TypeScript SDKs

Show HN: Turn OpenAPI to Universal TypeScript SDKs(speakeasyapi.dev)

27 points by simplesager 2 years ago | 5 comments

Hi HN! We’re excited to share our new code generator that lets you ship high-quality TypeScript SDKs, that your users will love, from your OpenAPI documents. Our ongoing goal is to help you build one SDK that runs anywhere modern JavaScript runs. This includes new runtimes like Deno and Bun in addition to the ever-popular Node.js. Additionally, the popularity of AI has meant server-sent events and file streaming are also commonplace - we wanted to cover these use cases too. This explosion in new runtimes and ways of interacting with APIs shifts cognitive burden on API developers often having to work with different technologies when integrating an API. At Speakeasy we set out to create a “Universal Typescript SDK” that would work across browser, servers and other runtimes.

There are a number of open source generators out there but none of them provided enough coverage across the variety of APIs we see modelled with OpenAPI. Some of the requirements we tried to hit in this release:

- Compatibility with the browser & server

- Support for popular, backend JavaScript runtimes including Node.js, Bun, Deno

- User input and server response validation with Zod

- Support for polymorphic types, also known as unions or `oneOf` in OpenAPI.

- Support for constant and default values, big integers and decimals

- Support for multipart streaming upload

- Support for server sent events using native OpenAPI constructs

We want to give a special shout out to Zod because it served as a great foundation for translating all the JSON Schema primitives used in OpenAPI into TypeScript types that you can trust. By this we mean that the types are backed by runtime validation so vanilla JS users have a safeguard and servers that drift from their OpenAPI spec are caught instead of silently failing or triggering obscure runtime errors. If you’re curious to dive into our learnings check out this post https://www.speakeasyapi.dev/post/how-we-built-universal-ts

We’d love for folks to check out our new generator and give us feedback. Its really easy to get started. Install our CLI with `brew install speakeasy-api/homebrew-tap/speakeasy` and run `speakeasy generate sdk -s openapi.yaml --output ./sdk -l typescript` . If you want to chat directly with us you can reach us on slack : https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1cwb... .

disintegrator 2 years ago |

Hey folks, this was my first major project at Speakeasy! Overall, it's been a great exercise in understanding the sort developer experience customers want from their SDKs. A couple of challenges I want to highlight included translating JSON Schema to Zod schemas (https://zod.dev/) and, frustratingly enough, deciding whether to distribute CommonJS or ESM. On the Zod side, it's been really nice to build on top of a strong schema validation library. It extended the static types we are generating into the runtime in a way. A few customers are using our SDK to detect when their deployed API has drifted from their OpenAPI specs. On the ESM/CJS side, it turns out, _a lot_ of folks (both customers and their users) still want CommonJS. Our testing also showed that bundlers are happy to tree-shake CommonJS code that is side-effect-free and importing CommonJS inside ESM worked just fine so we settled on CJS. We're actually generating source files that contain `import` statements and transpiling, using TypeScript, to CommonJS so we have the option to make this configurable as demand for ESM grows.

I'll be watching this post and replying to questions :)

rattray 2 years ago |

Nice, congrats!

This must have been a huge lift – when we launched support for browsers/bun/deno/node/etc along with CJS & ESM from the same npm package, it was a surprising amount of work.

(disclaimer, we offer a similar service: https://stainlessapi.com)

asmyers1793 2 years ago |

Wow, this is totally awesome! I like that you work with the Bun and Deno runtimes.

napolux 2 years ago |

WOW

anagpal 2 years ago |

great stuff!