# speakeasy-vs-openapi-generator
Source: https://speakeasy.com/blog/speakeasy-vs-openapi-generator

import { CardGrid } from "@/components/card-grid";
import { openApiGeneratorComparisonData } from "@/lib/data/blog/openapi-generator-comparison";
import { Callout, Table } from "@/mdx/components";

## OpenAPI Generation Overview

The [OpenAPI Generator project](https://openapi-generator.tech/) 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.

<CardGrid cards={openApiGeneratorComparisonData} heading="Speakeasy vs. OpenAPI Generator" />

## The cost of using `openapi-generator`

{/* <Testimonial
  variant="dark"
  avatar="/assets/blog/speakeasy-vs-openapi-generator/quote-headshots/roy-pereira.png"
  quoted="Roy Pereira, Unified.to CEO & Co-Founder"
>
  “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.”
</Testimonial> */}


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](https://dev.to/fastly/better-fastly-api-clients-with-openapi-generator-3lno) 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:

{/* <Testimonial variant="dark">
  “To ensure we would be able to run the code-generation process within
  our Continuous Integration (CI) pipeline, we needed to use
  a Dockerised version of openapi-generator-cli (the coordination of which was a
  complex process).”
</Testimonial> */}

{/* <Testimonial variant="dark">
  “Another challenge we encountered was the quality of the community-driven
  language templates. They worked but templates didn't appear to be well
  maintained over time, nor did every feature in our OpenAPI specification have
  a corresponding implementation in the language templates.”
</Testimonial> */}

{/* <Testimonial variant="dark">
  “Language templates **didn't support the latest programming language
  version**, and the generated documentation wasn't as good as we needed it to
  be.”
</Testimonial> */}

{/* <Testimonial variant="dark">
  “Our OpenAPI specification files would cause problems in the generator... Each
  of these issues would result in hard-to-debug compilation errors within the
  code-generation pipeline, and so we would have to figure out which of the
  three potential layers the issue was stemming from: 1. The Fastly OpenAPI
  specification documents. 2. The [openapi-generator mustache
  templates](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources).
  3. The [openapi-generator language
  parsers](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages) (written
  in Java).”
</Testimonial> */}

{/* <Testimonial variant="dark">
  “We had to iterate on both ends of the integration, a bit like trying to fit a
  square peg into a round hole, then gradually changing the shape of both the
  peg and the hole until they fit.”
</Testimonial> */}

{/* <Testimonial variant="dark">
  “Auto-generating our API clients has been a long project... The code generation
  itself hasn't been easy: we've had to balance the complexity of coordinating
  changes across multiple repositories while handling errors over multiple
  layers, and producing API clients that are not only idiomatic to the language
  they're built in but also correct and accessible.”
</Testimonial> */}

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.

<Callout title="TIP" type="default">
  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.
</Callout>


## 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](https://github.com/vercel/sdk/tree/main), generated on the Speakeasy platform:

```typescript filename="buyDomain.ts"
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


<Table
  data={[
    { feature: "Type-safety", speakeasy: "✅ Using Zod", openapiCodegen: "❌" },
    { feature: "Union types/polymorphism", speakeasy: "✅", openapiCodegen: "✅ Without discriminator" },
    { feature: "Documentation generation", speakeasy: "✅ Full docs & examples", openapiCodegen: "❌" },
    { feature: "OAuth 2.0", speakeasy: "✅", openapiCodegen: "❌" },
    { feature: "Webhooks", speakeasy: "✅", openapiCodegen: "❌" },
    { feature: "Retries", speakeasy: "✅", openapiCodegen: "❌" },
    { feature: "Pagination", speakeasy: "✅", openapiCodegen: "❌" },
    { feature: "Package publishing", speakeasy: "✅", openapiCodegen: "❌" },
    { feature: "CI/CD integration", speakeasy: "✅ GitHub Actions", openapiCodegen: "❌" }
  ]}
  columns={[
    { key: "feature", header: "Feature" },
    { key: "speakeasy", header: "Speakeasy" },
    { key: "openapiCodegen", header: "`openapi-codegen`" }
  ]}
/>

## 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.