Comparison guide: OpenAPI/Swagger TypeScript client generation

At Speakeasy, idiomatic SDKs are created in a variety of languages. The generators follow principles that ensure SDKs offer the best developer experience, allowing focus on building APIs while developer-users focus on delighting their users.

In this post, we’ll compare TypeScript SDKs managed by Speakeasy to those generated by open-source generators.

The TypeScript SDK generator landscape

We’ll compare the Speakeasy SDK generator to two generators from the OpenAPI Generators project and two additional popular open-source generators.

Our evaluation includes:

1. The TypeScript Fetch  generator from OpenAPI Generators.
2. The TypeScript Node  generator from OpenAPI Generators.
3. Oazapfts , an open-source generator with almost 400 stars on GitHub.
4. OpenAPI TypeScript Codegen , a popular open-source generator with 1,700 stars on GitHub.
5. The Speakeasy SDK generator.

Here’s the summary of how the different generators compare:

For a detailed comparison, read on.

Installing SDK generators

Although generator installation does not impact the resulting SDKs, your team will install the generator on each new development environment. We believe an emphasis on usability starts at home, and your internal tools should reflect this.

Install the Speakeasy CLI by running the following in the terminal:

Installing openapi-generator using Homebrew installs openjdk@11 and its numerous dependencies:

To install oazapfts and openapi-typescript-codegen, add them to an npm package as dependencies:

Downloading the Swagger Petstore specification

Before we run our generators, we’ll need an OpenAPI specification to generate a TypeScript SDK for. The standard specification for testing OpenAPI SDK generators and Swagger UI generators is the Swagger Petstore .

We’ll download the YAML specification at https://petstore3.swagger.io/api/v3/openapi.yaml  to our working directory and name it petstore.yaml:

Validating the spec

Both the OpenAPI Generator and Speakeasy CLI can validate an OpenAPI spec. Oazapfts and OpenAPI TypeScript Codegen don’t offer validation, so if we were to use them at scale, we would need a separate validation step.

To validate petstore.yaml using OpenAPI Generator, run the following in the terminal:

The OpenAPI Generator returns two warnings:

Validation using Speakeasy

We’ll validate the spec with Speakeasy by running the following in the terminal:

The Speakeasy validator returns ten warnings, seven hints that some methods don’t specify return values, and three unused components. Each warning includes a detailed, structured error with line numbers to help us fix validation errors.

Since both validators validated the spec with only warnings, we can assume that all our generators will generate SDKs without issues.

The Speakeasy validator includes an option to get hints on how to improve our schema. Use the --output-hints argument to activate this feature:

This provides a detailed list of hints, all of which would improve our eventual SDK users’ experience.

Here’s how the generators’ validation features compare:

Generating SDKs

Now that we know our OpenAPI spec is valid, we can start generating and comparing SDKs. First, we’ll create an SDK using Speakeasy and take a brief look at its structure. Then we’ll generate SDKs using the open-source generators and compare the generated code to the Speakeasy SDK.

Generating an SDK using Speakeasy

To create a TypeScript SDK using the Speakeasy CLI, run the following in the terminal:

The command above creates a new directory called petstore-sdk-speakeasy, with the following structure:

At a glance, we can see that Speakeasy creates documentation for each model in our schema and that it creates a full-featured npm package. Code is split between internal tools and the SDK code.

We’ll look at the generated code in more detail in our comparisons below, starting with OpenAPI Generator.

Generating SDKs using OpenAPI Generator

OpenAPI Generator is an open-source collection of community-maintained generators. It features generators for a wide variety of client languages, and for some languages, there are multiple generators. TypeScript tops this list of languages with multiple generators, with 11 options to choose from.

The two TypeScript SDK generators from OpenAPI Generator we tried are typescript-fetch  and typescript-node .

Usage is the same for both generators, but we’ll specify a unique output directory, generator name, and npm project name for each.

We’ll generate an SDK for each by running the following in the terminal:

Each command will output a list of files generated and create a unique directory. We specified an npm package name as a configuration argument, npmName, for each generator. This argument is required for the generators to create full packages.

Generating an SDK with oazapfts

To run oazapfts, we’ll either need to run it from the local JavaScript project bin folder or install it globally. We opted to run it from the bin folder.

Navigate to the local JavaScript project we created for petstore-sdk-oazapfts and run the following:

Oazapfts runs without any output and generates a single TypeScript file, index.ts. Remember that we had to install oazapfts as a runtime dependency. Let’s see what gets called from the dependency:

Code generated by oazapfts excludes the HTTP client code, error handling, and serialization. We can look at the runtime dependencies from Oazapfts itself, to get an idea of the dependency graph:

This is an excerpt from the oazapfts package.json file:

Some of these dependencies clearly relate to the generator itself. For example, we can assume that no SDK client would need access to swagger-parser at runtime.

Generating an SDK with OpenAPI TypeScript Codegen

As with oazapfts, we’ll need to run the OpenAPI TypeScript Codegen CLI from our npm binaries location, where it is aliased as openapi.

Navigate to the petstore-sdk-otc JavaScript project and run:

OpenAPI TypeScript Codegen uses the fetch API for requests by default, so it’s aimed at SDKs used in the browser. However, it can be configured to use Axios. We tried using Axios and noted that OpenAPI TypeScript Codegen does not create an npm package with dependencies, so we had to manually install a version of Axios.

By contrast, Speakeasy manages dependencies on behalf of the developer when generating an SDK, eliminating the need to guess which version of a dependency to install.

Polymorphism

The Petstore schema does not include examples of polymorphism in OpenAPI, so we’ll add two new schemas for Dog and Cat, and use them as input and output in the updatePet operation.

Add the following to the component schemas in petstore.yaml:

Then add discriminated unions  to the updatePet operation:

After regenerating the SDKs, let’s inspect each SDK’s updatePet method.

We see that oazapfts generates a method that type casts the input and output objects based on the discriminating field petType:

The SDK generated by typescript-fetch is slightly more verbose, and uses switch statements to derive the types for input and output objects:

OpenAPI Codegen adds a union for Cat and Dog on both input and output, but does not use the discriminator to add runtime type casting:

The typescript-node generator does not make use of types for unions in OpenAPI:

Here’s a summary of how each generator handles OpenAPI polymorphism:

Retries

The SDK managed by Speakeasy can automatically retry failed network requests or retry requests based on specific error responses.

This provides a straightforward developer experience for error handling.

To enable this feature, we use the Speakeasy x-speakeasy-retries extension in the OpenAPI spec. We’ll update the OpenAPI spec to add retries to the addPet operation as a test.

Edit petstore.yaml and add the following to the addPet operation:

Add this snippet to the operation:

Now we’ll rerun the Speakeasy generator to enable retries for failed network requests when creating a new pet. It is also possible to enable retries for the SDK as a whole by adding a global x-speakeasy-retries at the root of the OpenAPI spec.

React Hooks

React Hooks  are a popular way to manage state and side effects in React applications.

Speakeasy generates built-in React Hooks using TanStack Query . These hooks provide features like intelligent caching, type safety, pagination, and seamless integration with modern React patterns such as SSR and Suspense.

For example, in this basic implementation, the useQuery hook fetches data from an API endpoint. The cache key ensures unique identification of the query. The status variable provides the current state of the query: loading, error, or success. Depending on the query status, the component renders loading, error, or the fetched data as a list.

None of the other generators generate React Hooks for their SDKs.

For an in-depth look at how Speakeasy uses React Hooks, see our official release article .

Pagination

SDKs managed by Speakeasy include optional pagination for OpenAPI operations.

We’ll update our pet store schema to add an x-speakeasy-pagination extension and an offset query parameter:

After regenerating the SDK with Speakeasy, the getInventory operation includes pagination:

None of the other generators include pagination as a feature.

Auto-pagination

Speakeasy’s React Hooks also enable auto-pagination, which automatically fetches more data when the user scrolls to the bottom of the page. This feature is useful for infinite scrolling in social media feeds or search results.

None of the other generators include auto-pagination as a feature.

Data streaming

All the generators in our comparison generate SDKs that use the Fetch API, which enables streaming for large uploads or downloads.

Speakeasy creates detailed documentation as part of the SDK, detailing how to open large files on different runtimes to help your developer-users take advantage of streaming.

Generated documentation

Of all the generators tested, Speakeasy was the only one to generate documentation and usage examples for its SDK. We see documentation generation as a crucial feature if you plan to publish your SDK to npm for others to use.

Here’s how the generators add documentation:

Speakeasy generates a README.md at the root of the SDK, which you can customize to add branding, support links, a code of conduct, and any other information your developer-users might find helpful.

The Speakeasy SDK also includes working usage examples for all operations, complete with imports and appropriately formatted string examples. For instance, if a type is formatted as email in our OpenAPI spec, Speakeasy generates usage examples with strings that look like email addresses. Types formatted as uri will generate examples that look like URLs. This makes example code clear and scannable.

Here’s the usage example managed by Speakeasy after we update petstore.yaml to format the string items in photoUrls as uri:

Bundling applications for the browser

Speakeasy creates SDKs that are tree-shakable and can be bundled for the browser using tools like Webpack, Rollup, or esbuild.

Because Speakeasy supports a wider range of OpenAPI features, Speakeasy-created SDKs are likely to be slightly larger than those generated by other tools. Speakeasy also limits abstraction, which can lead to larger SDKs. This does not translate to a larger bundle size, as the SDK can be tree-shaken to remove unused code.

Any SDK that supports runtime type checking or validation will have a larger bundle size, but the benefits of type checking and validation far outweigh the cost of a slightly larger bundle. If you use Zod elsewhere in your application, you can exclude it from the SDK bundle to reduce its size.

Here’s an example of how to exclude Zod from the SDK bundle:

Automation

This comparison focuses on the installation and usage of command line generators, but the Speakeasy generator can also run as part of a CI workflow, for instance as a GitHub Action , to make sure your SDK is always up to date when your API spec changes.

A live example: Vessel API Node SDK

Vessel  trusts Speakeasy to generate and publish SDKs for its widely used APIs. We recently spoke to Zach Kirby about how Vessel uses Speakeasy. Zach shared that the Vessel Node SDK  is downloaded from npm hundreds of times a week.

Summary

The open-source SDK generators we tested are all good and clearly took tremendous effort and community coordination to build and maintain. Different applications have widely differing needs, and smaller projects may not need all the features offered by Speakeasy.

If you are building an API that developers rely on and would like to publish full-featured SDKs that follow best practices, we strongly recommend giving the Speakeasy SDK generator a try.

Join our Slack community  to let us know how we can improve our TypeScript SDK generator or to suggest features.