Overview

This repo contains different attempts for generating TypeScript SDKs from the Linode OpenAPI spesification using different tools.

Generating TypeScript SDKs from OpenAPI specifications can make frontend teams more efficent by automating the tedious work of mantaining the SDK.

Each folder in the packages directory represents a different tool being used to generate a TypeScript SDK. The examples directory is just used a manual playground for testing the generated SDKs.

Conclusion

I had the most success using https://heyapi.dev to generate a TypeScript SDK (see packages/openapi-ts).

With minor patching to the source OpenAPI spec, it generates a feature-rich fetch client, valid Zod schemas, and valid TypeScript types. Most types and schemas seem correct, but some are inaccurate due to inaccuracy and flaws in the source OpenAPI specification.

You view auto-generated reference docs of the SDK to get an idea of what the final result is like.

For teams and/or apps that want to auto-generate their API calls, types, and validation schemas from an OpenAPI specification, Hey API may already be a great option as shown in this proof of concept in packages/openapi-ts.

Once Hey API supports generating mock data (similar to Linode Cloud Manager's factories), using an auto-generated TypeScript SDK will be a very compelling option for Linode/Akamai apps.

Tools Tested

Hey API 🥇

You can see API reference docs for this generated SDK here!

Pros

• Generated mostly valid code (5 errors in 2 files according to TypeScript) without any patches to the OpenAPI spec
  • I got it down to 0 errors by patching the OpenAPI spec
• Has good defaults
• Easy to configure

Cons

• Does not support generating mock data like Kubb yet
  • Claims to be coming soon hey-api/hey-api#1485

Kubb 🥈

Pros

• More plugins in general
• Supports mock data tools like Faker which could be very useful for us

Cons

• Generated lots of invalid code (115 errors in 47 files according to TypeScript)
  • Have not tried patching yet to get this number down

Comparison Chart

This isn't comprehensive. It just highlights some key points between the tools.

	Hey	Kubb
Fetch Client	✅	✅
Axios Client	✅	✅
Ky Client	✅	✅
TypeScript types	✅	✅
Zod Schemas	✅	✅
React Query hooks	✅	✅
Mock Data	❌ (Coming soon)	✅
Angular support	✅	❌
Generates valid code	✅ (5 errors in 2 files according to TypeScript)	❌ (115 errors in 47 files according to TypeScript)

Future Work

This proof of concept repo doesn't fully automate SDK generation.

If I were to "finish" making it fully automated, I'd write Github Actions workflows that...

• automatically check for changes in the sourced OpenAPI spec
• sync the package.json version to match the OpenAPI spec's version
• and publish to npm

That's all it would take to fully automate an auto-generated TypeScript SDK!