Generate a Java SDK from OpenAPI / Swagger

Java SDK Overview

Speakeasy's Java SDK is designed to be easy to use and debug. This includes generating strongly typed classes that enforce required fields and other validations to ensure the messages sent are correct. This allows for a tighter development cycle so your API consumers can spend less time developing solutions using your API.

The core features of the SDK include:

  • Using properties on class fields and reflection-based serialization and deserialization of data
  • Object types used in place of primitive types when a field is optional
  • A utils package that provides shared code used by generated classes, making the generated code easier follow
  • Use of the factory pattern and the method chaining pattern to easily configure the SDK
  • Authentication support for OAuth flows and other standard security mechanisms
  • Support for date and date/time formats
  • Custom enums types using string or integer values

The SDK includes minimal dependencies. It only requires the Jackson Library (opens in a new tab) to serialize and deserialize data over the wire. The Java SDKs use to make HTTP requests.

Java Package Structure


|-- lib # parent for all generated source
| |-- build.gradle # more gradle configuration
| |-- build # directory that will contain built artifacts
| | └-- ...
| └-- src # source code directory
| └-- main # main source code directory
| └-- {SDK Package Name} # sub-directories to the SDK package namespace
| |-- # primary SDK class
| |-- ... # additional sub-SDK classes
| |-- models # package for model-related files
| | |-- operations # package for request/response operational models
| | | └-- ...
| | └-- shared # package for shared component models
| | └-- ...
| └-- utils # package for shared utility classes
| └-- ...
|-- docs # Markdown files for the SDK's documentation
|-- gradlew # gradle shellscript to build/install the SDK
|-- grewlew.bat # gradle batch file to build/install the SDK
|-- settings.gradle # provided gradle settings
|-- gradle
| └-- ... # other gradle related files
└-- ...

HTTP Client

The Java SDK HTTP client is completely configurable using a class implementing the following interface (found under the util package of the generated code):

public interface HTTPClient {
public HTTPResponse<byte[]> send(HTTPRequest request)
throws IOException, InterruptedException, URISyntaxException

A default implementation is provided based on Any developer using the SDK can replace this implementation their own implementation very easily:

MyHttpClient client = new MyHttpClient();
SDK sdkInstance = SDK.builder().setClient(client).build();

This gives them the flexibility to setup proxies, cookie jars, special headers, or any other low-level customization.

Java SDK Data Types & Classes

Where possible the Java SDK uses native types from the language or the object versions of primitive types, for example:

  • java.lang.String
  • java.time.DateTime
  • int (or java.lang.Integer)
  • long (or java.lang.Long)
  • float (or java.lang.Float)
  • double (or java.lang.Double)
  • boolean (or java.lang.Boolean)
  • etc...

The object versions of types are preferred in situations where an attribute is optional. This allows us to use the null value to signal that no value was present when a message was received or that no value will be set when sent. Primitive types are used whenever a value is required.


If configured, the Java SDK will generate methods with parameters as part of the method call itself rather than as part of a separate request object. This will be done for up to maxMethodParams parameters, that can be set in the gen.yaml file.

If the maxMethoParams configuration option is absent or set to zero, all generated methods require a single request object that contains all the parameters that may be used to call an endpoint in the API.


To handle errors in the Java SDK, you need to check the status code of the response. If it is an error response, then the error field of the response will be set the decoded error value.

Info Icon

Coming Soon

Support for throwing non-successful status codes as exceptions coming soon.