Comparison guide: OpenAPI/Swagger Python client generation

Many of our users have switched from OpenAPI Generator  to Speakeasy for their Python SDKs. Learn how to use both SDK creators in this guide, and the differences between them.

Open-source OpenAPI generators are great for experimentation but lack the reliability, performance, and intuitive developer experience required for critical applications. As an alternative, Speakeasy creates idiomatic SDKs that meet the bar for enterprise use.

In this post, we’ll focus on Python, but Speakeasy can also create SDKs in Go, TypeScript, Java, Ruby, PHP, and more.

Here’s a summary of the major differences between a Python SDK created using Speakeasy, compared to an SDK created by the OpenAPI Generator. Unless support for Python 3.7 is critically important, Speakeasy is recommended for Python SDKs.

For the full technical walkthrough, read on!

What is OpenAPI Generator?

OpenAPI Generator, as opposed to an OpenAPI generator, is a specific community-run open-source SDK generator for the OpenAPI specification, focusing on version 3 . The Swagger Codegen  tool is similar, but run by the company Smartbear. OpenAPI Generator was forked from Swagger Codegen.

Preparing the SDK generators

For our comparison, we ran Speakeasy and OpenAPI Generator each in its own Docker container, which works on Windows, macOS, or Linux. Using Docker instead of running code directly on your physical machine is safer, as the code cannot access files outside the folder you specify.

We used the PetStore 3.1 YAML schema file from the Swagger editor  examples menu in File > Load Example > OpenAPI 3.1 Petstore. To follow along with this guide, save the file to a subfolder called app in your current path, such as app/petstore31.yaml. We changed the schema to use the server version 3.1:

OpenAPI Generator provides a Docker image, but Speakeasy does not. To install the Speakeasy CLI, you can either install the Go binary directly on your computer following the steps in the Speakeasy Getting Started guide, or run it in Docker, which we did.

To use Docker yourself, first create a Docker file called se.dockerfile with the content below, replacing YourApiKey with your key from the Speakeasy website.

Then build the Speakeasy image with the command below.

Validating the schemas

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

Validation using OpenAPI Generator

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

OpenAPI Generator returns two warnings:

Validation using Speakeasy

Validate the schema with Speakeasy by running the following in the terminal:

The Speakeasy validator returns 72 hints about missing examples, seven warnings about missing responses, and three warnings about unused components. Each warning includes a detailed JSON-formatted error with line numbers.

Since both validators returned only warnings and not errors, we can assume both generators will create SDKs without issues.

Creating the SDKs

First, we’ll generate an SDK with OpenAPI Generator, and then we’ll create one with Speakeasy.

Generating an SDK with OpenAPI Generator

OpenAPI Generator includes two different Python SDK generators (and four server generators):

• python 
• python-pydantic-v1 

The only difference between the two is that python is the latest version, which uses Pydantic V2. You can ignore Pydantic V1.

To generate an SDK from the schema file in OpenAPI Generator, we ran the command given in the OpenAPI Generator readme  below.

This command gives one warning that looks like it could cause errors, o.o.codegen.utils.ModelUtils - Failed to get the schema name: null, but OpenAPI Generator successfully created three folders:

The generator warned us in the terminal that Generation using 3.1.0 specs is in development and is not officially supported yet. The OpenAPI Generator roadmap  hasn’t been updated in almost two years.

Creating an SDK with Speakeasy

Next, we’ll create an SDK using the Speakeasy CLI with the command below.

Speakeasy creates the following folders.

Unlike the OpenAPI Generator output, the Speakeasy output includes no tests.

SDK code comparison: Package structure

We’ll start our comparison by looking at the structure of each SDK: the OpenAPI Generator SDK and the Speakeasy SDK.

To count the lines of code in the SDKs, we’ll run cloc for each (ignoring documentation and test folders):

Below are the results for each SDK.

We see that the Speakeasy SDK has about the same number of lines of code and lines of comments as OpenAPI Generator, but OpenAPI Generator leaves more blank lines.

The following commands output the files of each SDK.

Below is the output for OpenAPI Generator.

The folder structure is simple and clear with nothing unexpected. Files are separated at the API level (pet, store, and user) and by model. There are a few helper files, like exceptions.py.

Below is the output for Speakeasy.

The Speakeasy SDK is more complex and has more features. Files are separated at a lower level than OpenAPI Generator — at the operation level - and further split into media types of the operation, like addpet_json.py. There are more helper files bundled with the SDK in the utils folder. The _hooks folder allows you to insert custom code into the SDK.

Calling the server

Swagger provides a complete test server for the PetStore OpenAPI version 3.1 server at https://petstore31.swagger.io . (There is a version 3.0 server too, but that gives 500 errors when called.)

To check that both SDKs contain code that actually works, we called the pet operations given in the readme files against the test server.

We used a Docker Python 3.8 container, as 3.8 is supported by both OpenAPI Generator and Speakeasy.

Calling the server with OpenAPI Generator

For OpenAPI Generator, we ran the command below, with a successful response. First, the command installs the Python dependencies in the Docker container as recommended in the SDK README.md file, then it runs the sample main.py script to call the server using the SDK.

The README.md does not give clear instructions for installing all dependencies. After running the installation commands above, pytest was not installed, even though it was mentioned in README.md.

Below is the main.py script to call the API.

The example code was partially given in README.md, but we needed to add the pet JSON sample from https://petstore31.swagger.io/#/pet/addPet .

Calling the server with Speakeasy

Speakeasy also called the server successfully. The command below is almost identical to the one for OpenAPI Generator in the previous section, except that the Speakeasy SDK has more dependencies than OpenAPI Generator. Poetry needs packages that are not included with a minimal Linux installation.

Before poetry install would work however, we had to comment out the invalid line in pyproject.toml:

Below is the main.py script to call the API. The code comes straight from the README.md file (except the print line), including the correct JSON to create a pet.

Models, data containers, and typing

Both SDKs use strong typing in their models.

The OpenAPI Generator and Speakeasy SDK models inherit from the Pydantic BaseModel class. Pydantic  validates data at runtime and provides clear error messages when data is invalid.

For example, creating a Pet object with the name field set to an integer value will result in a validation error:

Both SDKs create a BaseModel pet like below.

In addition, Speakeasy adds TypedDicts to its components. An example is from Pet.py below.

These typings provide strong runtime type checking and static type safety, which your IDE can use, too.

Speakeasy also has enums in models, which OpenAPI Generator does not. Below is an example from the pet model.

Contrast this enum with the string-based specification and validation created by OpenAPI Generator:

The OpenAPI Generator class also has to include many boilerplate methods for Pydantic, which is done for every model in the schema. Speakeasy models are more concise.

Open enums

Speakeasy allows adding the custom attribute x-speakeasy-unknown-values to an OpenAPI field to allow open enums.

The SDK code for an open enum doesn’t change much from a standard enum. It’s shown below.

Adding x-speakeasy-unknown-values will result in a Python SDK that allows values for status that are outside the given list of available, pending, and sold. There will no longer be a conflict between a new version of an API sending an unknown enum value to an older version of an SDK.

The disadvantage of this open enum technique is that it allows clients to send mistaken and incorrect values to the server.

The OpenAPI Specification has no way to handle enum conflicts between schema versions currently, and so OpenAPI Generator has no similar feature to open enums. A standard solution is still being debated on GitHub .

SDK dependencies

OpenAPI Generator and Speakeasy use almost identical Python packages.

OpenAPI Generator has the following dependencies in its requirements.txt file.

OpenAPI Generator also has a pyproject.toml file, though OpenAPI Generator does not mention this file in the installation instructions.

Speakeasy has the following dependencies in its pyproject.toml file.

HTTP client library

The OpenAPI Generator SDK uses urllib3 in its HTTP clients, while the Speakeasy SDK uses the urllib3 and the HTTPX  library.

HTTPX is future-proofed for HTTP/2 and asynchronous method calls. As per the Speakeasy SDK readme, you can call the server using synchronous or asynchronous calls, as shown below.

Supported Python versions

At the time of compiling this comparison, the Speakeasy SDK required at least Python version 3.8, which is supported until October 2024. The OpenAPI Generator SDK required at least Python version 3.7, which ended support halfway through 2023.

We recommend you use the latest Python version with both SDKs.

Retries

The SDK created by Speakeasy can automatically retry failed network requests or retry requests based on specific error responses. This provides a simpler developer experience for error handling.

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

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

Add this snippet to the operation:

Now we can rerun the Speakeasy creator 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 schema.

Created documentation

Both Speakeasy and OpenAPI Generator create a docs directory with documentation and usage examples.

We found the usage examples in the Speakeasy SDK worked flawlessly, while the examples in the OpenAPI Generator SDK don’t always include required fields when instantiating objects. For instance, the Pet.md example has the code below.

The OpenAPI Generator SDK’s documentation is especially thorough regarding models and has a table of fields and their types for each model. The Speakeasy SDK’s documentation is focused on usage, with a usage example for each operation for each model.

Speakeasy also creates appropriate example strings based on a field’s format in the OpenAPI schema.

For example, if we add format: uri to the item for a pet’s photo URLs, we can compare each SDK’s usage documentation for this field.

The SDK created by Speakeasy includes a helpful example of this field that lists multiple random URLs:

The OpenAPI Generator SDK’s documentation uses a single random string in its example:

Automation

This comparison focuses on installing and using Speakeasy and OpenAPI Generator using the command line, but both tools can also run as part of a CI workflow. For example, you can set up a GitHub Action  to ensure your Speakeasy SDK is always up to date when your API schema changes.

Unsupported features

At the time of writing, OpenAPI Generator does not support:

• Data types null, any, union, and UUID .
• OAuth and OpenID security .
• Multiple servers  (the place where clients call your SDK) and server URLs with parameters.
• Callbacks  (allowing your server to call a client).
• Link objects  (relating operations to each other to indicate a workflow).

Speakeasy supports all the features above. Nullable fields in a Speakeasy SDK are marked as Optional[].

Neither Speakeasy nor OpenAPI Generator supports XML requests and responses.

Summary

Open-source tooling can be a great way to experiment, but if you’re working on production code, the Speakeasy Python SDK creator will help ensure that you create reliable and performant Python SDKs.

The Speakeasy Python SDK creator uses data classes to provide good runtime performance and exceptional readability, and automatic retries for network issues make error handling straightforward. The Speakeasy-created documentation includes a working usage example for each operation. Finally, unlike other Python SDK creators, Speakeasy can publish your created SDK to PyPI and run it as part of your CI workflows.