API Advice

Building Speakeasy

Speakeasy vs OpenAPI/Swagger Generator

Sagar Batchu

January 10, 2025

OpenAPI Generation Overview

The OpenAPI Generator project (opens in a new tab) is a popular open-source tool for generating SDKs from OpenAPI/Swagger specifications. It has been an indispensable tool for the increasing number of companies which provide SDKs to their users. But, as any past user will know, there is a gap between what it is possible to achieve with off-the-shelf OSS and what’s required for supporting enterprise APIs.

Simply put, when users are paying for your API, they expect (and deserve) a high quality SDK: type-safety, authentication, pagination, retries and more. That is why Speakeasy was created. The platform has been designed to generate a best in class DevEx that can support enterprise APIs of any size & complexity.

In this article, we’ll dive into the business and high level technical differences between using Speakeasy to generate SDKs and using the OpenAPI Generators. If you want a granular breakdown for a specific language, check out our comparison guides.

Speakeasy vs. OSS generators

TypeScript

Fetch-based async client with Zod typing

Python

Sync & async client with Pydantic models

Go

Type-safe, idiomatic Go client

Java

Type-safe, builder-based Java client

C#

Type-safe, .NET-based C# client

PHP [beta]

Type-safe, Laravel-integrated client

The cost of using openapi-generator

“OpenAPI gen doesn’t work very well — the code often doesn’t look and feel right, and certain aspects of OpenAPI just aren’t handled well. We would probably still have needed to spend a ton of engineer time working around its limitations and quirks, and we decided that the headache wasn’t worth it.”

Roy Pereira, Unified.to CEO & Co-Founder

Open-source software is free, but that doesn’t mean it doesn’t have a cost.

The open-source projects have a number of issues that make it difficult to use in an enterprise:

• Spotty API feature coverage: There are holes in the OpenAPI generators that make it difficult to support moderately complex APIs. If your API uses OAuth, if it has union types, if it requires pagination, you’ll find that the generators fall short.
• Non-idiomatic code: The Open Source generators started off as a Java-based project. They are largely maintained by Java developers and consequently, many of the supported languages have a Java-like feel to them. This might not seem like a big deal, but it is massively off-putting to users if they are used to a language like Python or Typescript.
• Huge number of bugs: There are 4.5K open issues as of January 2025 — and growing ~10% every year.

The result of all these issues is that most enterprise users end up forking the repository and maintaining their own version of the Open Source generators with the fixes they need.

Enterprise case study: using openapi-generator at Fastly

Don’t just take our (or even our customers’) word for it, however. See what the API Architect of a publicly traded company posted (opens in a new tab) in Nov 2022 to mark his team’s completion of a project to develop SDKs using the Open Source generators. The post is equal parts celebration of the accomplishment and postmortem on the pain suffered.

Here are just a few key quotes from the post:

For an enterprise that wants to appeal to developers and showcase a compelling API experience, using Open Source successfully will require a significant investment in engineering resources, and significant time-to-market.

TIP

Total cost of ownership for OSS tooling is likely to be 3+ FTEs at a minimum, depending on the API surface area and SDK languages required. This is an ongoing commitment.

Generating handwritten SDKs with Speakeasy

When we set out to build our SDK generators, we wanted to deliver something that was 10x better than the existing generators. Our goal was to generate handwritten SDKs.

What constitutes a great SDK is somewhat subjective, but we set out some principles to guide development:

• Type safe - The SDKs we generate are fully typed, so that developers can catch errors early and often.
• Human readable - The SDKs we generate are easy for developers to read and debug. No convoluted abstractions.
• Minimal dependencies - Our SDKs are meant to be powerful but lean. We start with native language libraries and layer on third-party libraries only when the customer benefits far outweigh the cost of the extra dependency. We avoid adding unnecessary dependencies.
• Batteries-included - The SDKs we generate include everything from oauth, to pagination and retries.

With every language we support, we’re striving for an experience that’s instantly familiar to developers. As an example, check out this code snippet from Vercel’s TypeScript SDK (opens in a new tab), generated on the Speakeasy platform:

import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.domains.buyDomain({
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
    requestBody: {
      name: "example.com",
      expectedPrice: 10,
      renew: true,
      country: "US",
      orgName: "Acme Inc.",
      firstName: "Jane",
      lastName: "Doe",
      address1: "340 S Lemon Ave Suite 4133",
      city: "San Francisco",
      state: "CA",
      postalCode: "91789",
      phone: "+1.4158551452",
      email: "jane.doe@someplace.com",
    },
  });

  // Handle the result
  console.log(result);
}

run();

Generator Comparison Table

Summary

The OpenAPI Generators are great for the ecosystem, because they establish a baseline. But our commitment at Speakeasy is create a platform that is 10x better than using openapi-generator. We encourage you to try it out for yourself and see the difference.