Speakeasy vs Open Source: OpenAPI Go Client Generation

Speakeasy generates idiomatic Go SDKs based on OpenAPI specifications.

In this post, we'll take a look at why many of our users choose to switch from OpenAPI Generate and other open-source generators to Speakeasy to generate their Go SDKs.

Open-source SDK generators play an important role in experimentation and smaller custom integrations but we believe that teams should publish high-quality SDKs for their APIs that offer the best developer experience. Usable SDKs drive adoption by making it easier for developers to switch to your API.

At Speakeasy, we generate idiomatic client SDKs in a variety of languages. Our generators follow principles that ensure we generate SDKs that offer the best developer experience so that you can focus on building your API, and your developer-users can focus on delighting their users.

Go SDKs generated by Speakeasy are:

1. Well documented, with clear working examples for all operations.
2. Strongly typed, using pointers for optional objects to make it easy to distinguish between empty fields and zero values.
3. Lightweight, with few dependencies.
4. Customizable using Speakeasy extensions to the OpenAPI spec.

Go SDK Generator Options

We'll compare four Go SDK generators:

1. The Go generator (opens in a new tab) from the OpenAPI Generator (opens in a new tab) project.
2. oapi-codegen (opens in a new tab), an open-source OpenAPI Client and Server Code Generator.
3. ogen (opens in a new tab), an open-source OpenAPI v3 code generator for Go.
4. The Speakeasy SDK generator.

Installing SDK Generators

To start our comparison, we installed all four generators on a local machine running macOS.

Installing the OpenAPI Generator CLI

OpenAPI Generator depends on Java, which we covered at length previously. We concluded that managing the OpenAPI Generator Java dependencies manually just wasn't worth the effort.

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

This adds the openapi-generator CLI to our path.

Installing oapi-codegen

We install oapi-codegen using the Go package manager:

This command installs the oapi-codegen Go module and its dependencies (opens in a new tab).

Installing ogen

We followed the ogen quick start (opens in a new tab) to install ogen:

This installs the ogen Go module with its dependencies (opens in a new tab).

How To Install the Speakeasy CLI

To install the Speakeasy CLI, follow the steps in the Speakeasy Getting Started guide.

In the terminal, run:

Next, authenticate with Speakeasy by running the following:

This installs the Speakeasy CLI as a single binary without any dependencies.

Downloading the Swagger Petstore Specification

Before we run our generators, we'll need an OpenAPI specification to generate a Go SDK for. The standard specification for testing OpenAPI SDK generators and Swagger UI generators is the Swagger Petstore (opens in a new tab).

We'll download the YAML specification at https://petstore3.swagger.io/api/v3/openapi.yaml (opens in a new tab) to our working directory and name it petstore.yaml:

Validating the Spec

Both the OpenAPI Generator and Speakeasy CLI can validate an OpenAPI spec. We'll run both and compare the output.

Validation Using OpenAPI Generator

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 any return values and three unused components. Each warning includes a detailed JSON-formatted error with line numbers.

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

Generating an SDK

Now that we know our OpenAPI spec is valid, we can start generating SDKs.

We'll generate each SDK in a unique subdirectory, relative to where we saved the petstore.yaml spec file.

OpenAPI Generate

OpenAPI Generator features SDK generators for multiple languages, often with multiple options per language. We'll test the Go generator in this post.

We'll generate an SDK by running the following in the terminal:

This command will print a list of files generated and populate the new petstore-sdk-go-openapi directory.

Generating an SDK Using oapi-codegen

Before we generate an SDK using oapi-codegen, we'll need to create a new directory for this SDK.

Run the following in the terminal:

Create a Go module in the new directory:

Then run the oapi-codegen Go module:

Generating an SDK Using ogen

We followed the ogen quick start documentation.

Create a new directory for our ogen SDK and navigate to it in the terminal:

Create a new Go module in this directory:

Copy the petstore.yaml spec into this directory:

Create a new file called generate.go with the following contents:

Then run the following from our new directory:

In our testing, this resulted in a stack trace and returned an error status:

The function isParamAllowed in gen/gen_parameters.go on line 184 throws the error that nested objects are not allowed in form parameters. This seems to indicate that ogen does not yet support generating an SDK for a form request that takes nested objects as parameters, such as a pet's tags, when updating a pet in our schema.

The ogen documentation references a spec to download, so we'll replace petstore.yaml with their spec by running the following:

With this new simplified spec, we'll try the generator again:

The generator runs without errors and prints a log line:

This log line seems to indicate that some operations don't return a default response.

Speakeasy Generate

Finally, we'll generate an SDK using the Speakeasy CLI.

This command prints a log of warnings and information, then completes successfully.

SDK Gode Compared: Package Structure

We now have four different Go SDKs for the Petstore API:

• ./petstore-sdk-go-openapi/, generated by OpenAPI Generator.
• ./petstore-sdk-go-oapi-codegen/, generated by oapi-codegen.
• ./petstore-sdk-go-ogen/, generated by ogen.
• ./petstore-sdk-go-speakeasy/, generated by Speakeasy.

We'll start our comparison by looking at the structure of each generated SDK.

Let's print a tree structure for each SDK's directory. Run tree in the terminal from our root directory:

We'll split the output by directory for each SDK below.

OpenAPI Generator SDK Structure

OpenAPI Generator creates a relatively flat directory structure, with dedicated directories only for a copy of the spec (api/openapi.yaml), documentation (docs/), and tests (test/).

oapi-codegen SDK Structure

oapi-codegen creates only one file for all generated code, with no tests or documentation outside this file. This generator appears to be better suited to generating a small and specific client or server as part of a larger project, rather than generating a usable SDK that can be packaged for users.

ogen SDK Structure

ogen also generates relatively few files, which does not seem to be because this generation was based on a simpler spec. This generator does not seem to split schemas into different files and does not create any tests or documentation.

Speakeasy SDK Structure

Speakeasy generates a clear file structure, split into directories for models, types, and other utils. It also creates documentation, split by models and endpoints.

Models

Let's compare how a pet is represented in each of the four SDKs:

OpenAPI Generator Pet Model

OpenAPI Generator does not seem to take the spec's enum for pet status when generating the pet model. Status in this model is a pointer to a string, while other generators create a type to validate the status field. This model includes struct tags for JSON only.

oapi-codegen Pet Model

The oapi-codegen pet model is similar to the OpenAPI Generator version, but it makes the Tags field a pointer to a slice of Tag, making it possible for this field to be nil (which would be omitted from the JSON due to omitempty).

The Status field is not a simple string pointer, but a pointer to PetStatus, which provides better type safety, since PetStatus is a type alias for string with specific allowable values.

ogen Pet Model

The pet model generated by ogen lacks the Tags and Category fields because these fields are not present in the simplified spec used.

This struct uses a different approach to optional fields. It uses OptInt64 and OptPetStatus types. We'll look at how ogen differs from Speakeasy in terms of nullable fields below.

Speakeasy Pet Model

This struct is similar to the OpenAPI Generator version but includes additional form struct tags, which are likely used to specify how these fields should be encoded and decoded when used in form data (such as in an HTTP POST request).

Like the oapi-codegen version, Status is a *PetStatus rather than a *string.

Nullable Fields

Let's focus on the difference between how ogen and Speakeasy handle the nullable Status field.

Here's the relevant code generated by ogen:

While much safer than the OpenAPI Generator's pointer to a string type, the ogen OptPetStatus is not idiomatic and provides no benefit over using pointers, as Speakeasy does:

The Speakeasy approach provides the same strong typing as the ogen version. It defines PetStatus as a custom string type and defines allowable values as constants. This practice ensures that you can't accidentally set a PetStatus to an invalid value.

The way Speakeasy handles the PetStatus type is more idiomatic to Go, which generally favors simplicity and readability. Instead of defining a new struct like OptPetStatus, Speakeasy uses a built-in language feature (pointers) to achieve the same effect. This approach is simpler, more consistent with the rest of the language, and easier to understand and use.

SDK Dependencies

The ogen and oapi-codegen SDKs don't add any dependencies to the generated modules, so we'll compare dependencies between OpenAPI Generator and Speakeasy SDKs.

We'll run the following for each of these two SDKs:

For Speakeasy, this command prints the following:

The output for the OpenAPI Generator version is too long to show here, so we'll do a count instead:

Speakeasy purposefully generates SDKs with fewer dependencies, which leads to faster installs, reduced build times, and less exposure to potential security vulnerabilities.

To see why the Speakeasy SDK depends on an exponential backoff module, let's discuss retries.

Retries

The SDK generated by Speakeasy can automatically retry failed network requests or retry requests based on specific error responses, providing a straightforward developer experience for error handling.

To enable this feature, we need to use the Speakeasy x-speakeasy-retries extension to 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 global x-speakeasy-retries at the root of the OpenAPI spec.

Generated Documentation

Both Speakeasy and OpenAPI generate documentation for the generated code.

Each generator creates a README.md file at the base directory of the generated SDK. This file serves as a primary source of documentation for the SDK users. You have the option to customize this README using Speakeasy to suit your needs better. For example, you could add your brand's logo, provide links for support, outline a code of conduct, or include any other information that could be useful to the developers using the SDK.

The Speakeasy-generated documentation really shines when it comes to usage examples, which include working usage examples for all operations, complete with imports and appropriately formatted string examples. For instance, if a string 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.

We'll test this by adding format: uri to the items in the photoUrls array. Let's compare the generated example code for the addPet endpoint after adding this string format.

Usage Example Generated by OpenAPI

Here's the example from the OpenAPI-generated documentation:

Note how the OpenAPI example only includes required fields and ignores the URI string format from our spec.

Usage Example Generated by Speakeasy

This is what Speakeasy generates as a usage example:

The example generated by Speakeasy includes all available fields and correctly formats the example string in the PhotoUrls field.

We'll also compare how OpenAPI and Speakeasy generate documentation for the Status field in our pet model.

OpenAPI Generate Does Not Document Enums

The OpenAPI-generated documentation reflects the generated code's omission of valid options for the Status field. Here's the pet model documentation generated by OpenAPI:

Pet Properties Generated by OpenAPI

Note how Status is simply a string, with no indication of possible values.

Speakeasy Generates Documentation Showing Valid Values

Here's how Speakeasy documents the pet model:

Pet Fields Generated by Speakeasy

In the example above, PetStatus links to the following documentation:

PetStatus Values Generated by Speakeasy

This further illustrates Speakeasy's attention to detail when it comes to documentation.

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 (opens in a new tab), to make sure your SDK is always up to date when your API spec changes.

Summary

We've seen how Speakeasy generates lightweight, idiomatic SDKs for Go.

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

Join our Slack community (opens in a new tab) to let us know how we can improve our Go SDK generator or to suggest features.