OpenAPI PHP SDK creation: Speakeasy vs open source

Many of our users have switched from OpenAPI Generator  to Speakeasy for their PHP 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.

Here’s the high-level summary of the differences between Speakeasy and OpenAPI Generator:

In this post, we’ll do a technical deep dive on creating PHP SDKs using both Speakeasy and OpenAPI Generator, then we’ll compare the generated SDKs.

What is OpenAPI Generator?

OpenAPI Generator (not to be confused with a generic OpenAPI generator) is a community-run, open-source tool for generating SDKs from OpenAPI specifications, with a focus on version 3 . OpenAPI Generator originated as a fork of Swagger Codegen , a similar tool maintained by Smartbear.

Preparing the SDK generators

For our comparison, we ran Speakeasy and OpenAPI Generator in separate Docker containers, which work on Windows, macOS, and 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.

To follow along with this guide, locate the PetStore file in File -> Load Example -> OpenAPI 3.1 Petstore and save it to a subfolder called app in your current path, such as app/schema.yaml.

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

To use Docker, first create a 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 schema.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 return only warnings and not errors, we can assume both generators will create SDKs without issues.

Creating the SDKs

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

Creating an SDK with OpenAPI Generator

OpenAPI Generator includes three different PHP SDK creators (and six server creators). We’ll use the stable PHP creator , as the others are in beta testing and have fewer features.

To create an SDK from the schema file using OpenAPI Generator, we ran the command below, which we found in the OpenAPI Generator README .

OpenAPI Generator creates three folders:

A warning from OpenAPI Generator in the terminal read:

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 gives multiple warnings about xml request bodies are not currently supported and creates the following folders.

Speakeasy does not create test stubs, as unit testing is performed on Speakeasy’s generator instead of the generated SDK. Shipping unit tests for generated SDKs adds unnecessary complexity and dependencies.

Calling the server

Swagger provides a complete test server for the PetStore OpenAPI 3.1 schema at https://petstore31.swagger.io .

We called the pet operations given in each SDK’s README file against the test server to check that the SDKs contain working code.

We used a Docker Composer 2.7  container, which is based on Alpine 3 and PHP 8.

Calling the server with the OpenAPI Generator SDK

We used the app/og/main.php script below to call the API with the SDK generated by OpenAPI Generator. The example code was mostly given in the README.md file.

To get access to the folder to create the script, give yourself permissions to the shared Docker volume with the command below, using your username.

Next, we ran the command below and received a successful response.

The response of $apiInstance->addPet($pet) is below.

First, the command installs the PHP dependencies in the Docker container as recommended in the SDK README.md file, then it runs the sample main.php script to call the server using the SDK.

Calling the server with the Speakeasy SDK

The SDK Speakeasy creates also calls the server successfully.

Below is an example script to call the API with the SDK created by Speakeasy. Save it as app/se/main.php.

In the example above, we use the Components namespace to create a typed security object and a typed request object. We then call the addPetForm operation on the pet object in the SDK. You’ll notice that the SDK helps you validate the input data with enums and typed subobjects.

Let’s run the script to see the response.

The command to run the script is nearly identical to the command the OpenAPI Generator SDK used, except for using the Speakeasy folder.

The response of $sdk->pet->addPetForm($request) is below.

Package structure

Let’s compare the structure of the SDKs in terms of code volume and folder structure.

You can count the lines of code in the SDKs by running cloc for each (ignoring documentation and test folders):

Below are the results for each SDK.

We see that the Speakeasy SDK has five times as many files as OpenAPI Generator, but 40% less code. The libraries Speakeasy uses, as well as shared utility functions, allow it to create more concise code than OpenAPI Generator.

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 ApiException.php.

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 content types of the operation, like AddPetJsonResponse.php. There are more helper files bundled with the SDK in the Utils folder.

Code readability

We’ll compare the SDKs in terms of code readability, focusing on the Pet model first.

OpenAPI Generator

The Pet model generated by OpenAPI Generator inherits a ModelInterface and has a container property that holds the model’s fields. The model’s constructor can either take an associative array of field names and values or no arguments. Then, the model exposes getter and setter methods for each field.

Type mapping is presented as an associative array of field names and types as strings. The Pet model has the following fields:

Overall, the Pet model is extremely verbose, coming in at 623 lines of code, including comments and whitespace, but excluding dependencies.

Contrast this with the Pet model generated by Speakeasy.

Speakeasy

The Pet10 model generated by Speakeasy is more concise and readable, presented in its entirety below:

The Pet10 model, at 76 lines of code, including comments and whitespace, is more concise and readable than the Pet model generated by OpenAPI Generator. Speakeasy uses modern PHP features like typed properties, attributes, and named arguments to make the model more readable.

Serialization and deserialization are handled by JMS/Serializer , which uses annotations in the model to convert objects to and from JSON. This allows Speakeasy to create more concise and readable code.

Instead of using a getter and setter for each field, Speakeasy uses typed properties and a constructor to set the fields. This makes implementing the model more straightforward and less verbose.

Dependencies

The OpenAPI Generator SDK Composer file has the dependencies below.

• The ext-curl, ext-json, and ext-mbstring PHP extensions, which handle calling HTTP, serialize objects to JSON, and work with Unicode.
• Guzzle  and Guzzle PSR-7  send HTTP requests with PSR-7  support.
• PHPUnit  runs tests.
• Symfony PHP Coding Standards Fixer  formats code.

The Speakeasy SDK Composer file has the dependencies below.

• Guzzle  sends HTTP requests.
• Serializer  converts PHP objects to and from JSON and XML to be sent over HTTP.
• Brick\DateTime  manages dates, times, and time zones.
• phpDocumentor TypeResolver  generates types from DocBlocks.
• Laravel Pint  formats code.
• PHPStan  finds errors and handles complex types.
• PHPUnit  runs tests. However, there are no tests in the created SDK.
• Rector  checks code quality.
• Roave Security Advisories  warns about dangerous Composer dependencies.

Both creators use similar libraries, but OpenAPI Generator relies as much as possible on core PHP extensions, while Speakeasy has more serialization and complex typing libraries: Serializer, Brick, TypeResolver, and PHPStan.

Supported PHP versions

At the time of compiling this comparison, the Speakeasy SDK required at least PHP version 8.1. PHP 8 introduced language features to support stronger typing.

The OpenAPI Generator SDK still supports PHP version 7.4, though it is compatible with PHP 8.

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

Strong typing

Both creators use DocBlocks to provide type annotations to all parameters and variables in the SDKs, which is useful for IDEs and for programmers to understand the code.

But files in the Speakeasy SDK include the line declare(strict_types=1);, which causes PHP to throw a TypeError if a function accepts or returns an invalid type at runtime. The OpenAPI Generator SDK files do not have this line and so don’t check types at runtime.

In Speakeasy, the JMS Serializer checks types when converting from JSON to PHP objects at runtime. OpenAPI Generator doesn’t have this in plain Guzzle.

Enums

OpenAPI Generator provides a workaround for enumerations using constant strings and functions. Below is the pet status enumeration for OpenAPI Generator.

Below is the pet status enumeration for Speakeasy using modern PHP.

Content types

Below are the content types in the schema for updating a pet, in JSON, XML, or as a form.

Speakeasy supports JSON and form content types, but not XML. OpenAPI Generator supports all three. Additionally, OpenAPI Generator provides asynchronous versions of each HTTP call, such as AddPet and AddPetAsync.

In Speakeasy, each content type for each operation will become its own file in the SDK. In OpenAPI Generator, all operations are combined into one API file.

Unions

In OpenAPI, you can use oneOf in a schema like this:

The age property will be typed as a union in PHP in Speakeasy:

OpenAPI Generator can handle this schema, but creates a 380-line file called PetAge.php with custom code to implement unions.

Created documentation

Both Speakeasy and OpenAPI Generator create a docs directory with Markdown documentation and PHP usage examples for every operation and every model.

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 PetApi.md example in the OpenAPI Generator SDK doesn’t include any fields for the Pet object.

Both SDKs include detailed documentation for operations and models, but the Speakeasy SDK includes more detailed usage examples that work out of the box.

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, UUID , all, any, and union .
• Server URLs with parameters .
• Callbacks  (allowing your server to call a client).
• Link objects  (relating operations to each other to indicate a workflow).

Neither service supports OAuth 2 flows other than Implicit.

Summary

Open-source tooling can be a great way to experiment, but if you’re working on production code, the Speakeasy PHP SDK creator will help ensure that you create reliable and performant PHP SDKs. The Speakeasy PHP SDK creator uses strong typing to provide safe runtime performance, supports many OpenAPI features, and is rapidly adding more.