HN Explorer

Show HN: An opinionated and statically-typed TypeScript SDK generator (easysdk.xyz)

81 points by simplesager ↗ HN
Hi Hacker News!

My name is Sagar, I’m working on a startup called Speakeasy - we’re making all APIs self-service. The platform is currently in beta, but we’re independently launching this tool which you can use to generate language-idiomatic, statically-typed TS SDKs from any public OpenAPI schemas. We hope to continue iterating on this to give devs a way to easily generate high fidelity client SDKs for all the major languages.

Inspiration for this product is from past experiences struggling with OpenAPI. I was originally optimistic about using the OpenAPI tools to build out our offering, but quickly realized that the tools left a lot to be desired, and would not have provided our end users with the developer experience we wanted. While it’s not exhaustive, we’ve tried to address some of the biggest gaps in this tool:

* Low-dependency - To try and keep the SDK isomorphic (i.e. available both for Browsers and Node.JS servers), we wrap axios, but that’s it.This is intended to be idiomatic typescript; very similar to code a human would write; with the caveat that the typing is only as strict as the OpenAPI specification.

* Code just like a human would write - At this point static typing is everywhere. So wherever possible, we generate typed structures, construct path variables automatically, pass through query parameters, and expose strictly typed input / output body types.

* Future direction - There’s value in being neutral, but we felt like there is more value in being opinionated. In the future we’ll add features like built-in Pagination, Retries (Backoff/Jitter etc), Auth integrations, which should be handled in the SDK.

We’re planning to continue improving this service, so would love to hear what you think of the choices we’ve made, the issues we should address next, and what languages we should work on supporting.

46 comments

[ 2.8 ms ] story [ 112 ms ] thread
fcoury
Congrats on the launch!

I think it might be interesting to provide some examples without the need to upload a schema, since I assume most people playing with it won't have one ready right off the bat.

jzig
You can go to the Swagger Editor [1], download the default Pet Store schema as a JSON file, and upload it here to see an example in action.

[1]: https://editor.swagger.io/

Edit: Apparently their URLs are public, so here is the Pet Store schema I uploaded https://easysdk.xyz/sdk/openapi.json-a09be341882b7aa7b87eb40...

swatcoder
`[k: string]: unknown;`

It looks like all the data interfaces add this, which will (a) happily swallow typos, and (b) give you no warning that you might be pushing extra (i.e. private) data to the remote.

I understand that some people like the flexibility it provides, but it would be nice for that to be an option. There's no way I'd use the generated types with that, and the tool has a lot less value if I still have to go in and modify its output by hand.

ThomasRooney
This is a really good point. The generated SDK is configured to allow a super-set of the API request body to hit the backend, which could expose unnecessary data fields if passed in by client code.

It comes because we’re a bit pragmatic: if a user doesn’t specify their full data structure in their OpenAPI specification, and we can’t generate a strict type, we allow an arbitrary structure to reach the backend. In our experience the hard bit isn’t really writing the SDK, it’s making and maintaining a good OpenAPI spec (hence part of the commercial product we’re moving towards is the ability to generate a strict OpenAPI specification directly from handler code / traffic analysis in a backend server). Your concern is totally valid, and this is something we will make configurable.

crumbaugh
Looks pretty cool. Any eta on golang support?
ndimares
No firm ETA right now, but it's something we're currently working on :)

Will send you a private message when it's ready.

yodon
You're working on golang support but don't even have C# listed on your roadmap?

Looking at the TIOBE index, the market for C# language products is more than 5x bigger than the market for golang products.

Golang might be more popular here on hacker news, but if you're running a business, C# is a disproportionately important language compared to what you'd think if you only read posts on HN.

yodon
Nice! Any plans for generating C# sdk's?
ndimares
We're working on expanding the generator to be able to easily add new languages. Will definitely look at supporting C#!
simplesager
Would love to know more about this , how do you plan on using it ?
benbristow
I feel a bit spammy as I just commented on a comment a bit higher with the same thing, but NSwag will do the trick for you.

https://github.com/RicoSuter/NSwag

Works a treat and is open-source, integrates nicely with ASP WebAPI projects. Can even generate TypeScript clients with a choice of HTTP library (axios/fetch etc.) or even an Angular based client.

yodon
Thanks - NSwag had already been on my list to look at next week. The difference I see is that NSwag GitHub page is many screen heights long and it looks like I'm going to have to spend a bunch of time figuring it out. EasySDK was just click to upload a swagger file and I have a great looking TypeScript SDK, done.
yodon
Following up on this, the NSwag docs are definitely not as user friendly as the EasySdk site, but I was able to install and run the windows GUI app for NSwag and compare handling of a moderately large swagger file. EasySDK generated a TypeScript file that was 1/4 the size, far more readable, and from what I could tell as capable as the NSwag generated TypeScript file. That said, NSwag can generate C# files which EasySdk can not do (yet). Kiota (mentioned elsewhere in the comments) was unable to parse the swagger file.
ThomasRooney
Hey all ! I worked on this with Sagar a couple weeks back. The tl;dr of this is that it generates a (in my heavily-biased opinion) relatively clean SDK given an OpenAPI schema, similar to what a human would write. We’d used several other OpenAPI SDK generators but found their result to be a bit too big (and not tree-shakable); so spent a bit of effort trying to work out a way to compile-in the OpenAPI spec into a thin (but statically typed) wrapping around axios — very similar to an SDK coded manually.

Here's a few examples:

1. The Petstore API (an tiny example): https://easysdk.xyz/sdk/petstore.json-7bb7c53e017c0f7432f7bd...

2. Our own API: https://easysdk.xyz/sdk/openapi.yaml-ee89154ee9cf9a77f9fb07d...

3. The LOTR API: http://easysdk.xyz/sdk/lotr.yaml-f1ec4cde1ca7839dca2685e283e...

The generator works by:

1. Dereferencing an OpenAPI specification into something with inline types. (Ideally we'd handle type references rather than inlining them, but haven't got there yet)

2. Walking the type-graph, and mapping it to Operations (a combination of Path and Method).

3. Using the Typescript SDK, generating the SDK via creating AST nodes whilst walking the type graph.

4. Trying to compile in:

    1. Path Parameters as ES6 Template strings (e.g. `"/v1/apis/{apiID}/api_endpoints"` => `/v1/apis/${props.apiID}/api_endpoints`)

    2. Query params into axios parameters

    3. Body params as an additional argument to the SDK
It's not perfect, but we've used this to help run our own unit tests (and have a few customers trying it out too)! Happy to answer any questions
kbanman
Congrats on launching!

For anyone looking for more (open-source) alternatives, here's one I just discovered today: https://microsoft.github.io/kiota/

benbristow
I've had success with NSwag for generating both TypeScript and C# clients. Highly customisable - maybe too customisable with the config being quite complex - there's CLI & GUI tools to generate configs though.

https://github.com/RicoSuter/NSwag

We use the C# client generator in our public sector project and package the results up within Nuget, works a treat.

simplesager
Yeah Nswag is great, but pretty specific to the .NET ecosystem if i understand correctly ? Ideally we'd like this to become a universal generator where any dev/team/company publishing an API gets typed and idiomatic clients, including the long tail of languages.
benbristow
It can work with any Swagger/OpenAPI spec AFAIK, does run on .NET though. Other than running it if you're just generating a TS client you don't need to be part of the .NET ecosystem at all.

But I like your idea of the universal generator. NSwag isn't the most friendly of things to configure & regenerate so something like your lovely site will make it easier for people. Best of luck with the project!

AChelikani
Congrats Sagar and team - excited that someone is working on this! OpenAPI generator and swagger codegen has almost always produced unreadable and unusable SDKs for me, especially when my schema contains any model composition or polymorphism with allOf/anyOf/oneOf.

Have you guys written this entirely from scratch or done your own mustache templating on top of openapi-generator?

simplesager
We used a forked version of https://github.com/readmeio/oas to help dereference `$ref` statements, but other than that this is entirely hand-written: The Typescript `factory` AST API + `prettier` for formatting.
simplesager
yeah i was always annoyed how machine like the stubs that it generated are. I did here that they invested on making the go SDK more idiomatic. We've been exploring using templating or taking this approach of writing the generators from scratch in the native language.
irinaid
Congrats on the launch, this looks great and I'm looking forward to using it!
lagrange77
Interesing product, congrats!

Would you mind to share, how the animation was made? I would imagine sth. like blender + after effects + lottie..

ndimares
Thanks! Spot on. For embedding in the site, we used a lottie animation with the lottie-web NPM library. As for the lottie animation, I worked with a contractor on fiverr (this is him: https://www.fiverr.com/meerazzum?source=order_page_summary_s...). Would absolutely recommend him. I gave him a sloppy figma mockup and he brought it to life.

Let me know if you have more questions.

lagrange77
Thank you for the comprehensive answer, yeah he is good!
nurettin
Reminds me of how visual studio used to produce .net client code in vb or c# when you gave it a wsdl URL. You could do the same thing with Delphi. It had a command line program to generate a client interface. And a Ruby gem could just generate calls on the fly with method_missing. Turns out that having a web service definition language and concrete types to generate it automatically is a really useful thing. A thing that we somehow seem to have lost on the road.
simplesager
Yeah totally agree - unfortunate that OpenAPI so much flexibility that there are multiple ways to define the same operations. For api users having the concrete types just means faster integration, no ambiguity on what is/is not supported.
[deleted]
(comment deleted)
kamilafsar
Wow, what a coincidence :D We are about to launch something similar: https://samen.io
simplesager
very cool ! So Samen is a way to manage types across frontend and backends?
kamilafsar
Thanks! Yes, it will do that automatically by generating an SDK for your client (which will include all types you expose on your backend).
simplesager
i see you went the way of having a basic IDL ? looks nice and succint like protobuff
simplesager
the web world is missing a nice IDL - OpenAPI is honestly way too much !
[deleted]
(comment deleted)
cuddlecake
Hi, congrats on the launch.

On my screen, the website is scrollable. Not sure if the animation needs to have top: 30vh and height: 80%

Also: there is a big layout shift right after loading.

simplesager
Client SDKs are a great way to provide a normalised and predictable experience for customers but we're also working on tools for API Producers to self service all parts of the API integration experience. Check out our website! https://www.speakeasyapi.dev/.
tyho
This has been something I have desperately wanted for years now. The execution looks very good.

This easily shaves hours off a production quality api integration.

simplesager
Thanks tyho - let us know if you have any feedback !
memat
this is amazing and was months of work at my prev job to build internally. After it was built it freed up a whole dev team to do more mission critical work.