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 java.net.HttpClient to make HTTP requests.

Java Package Structure

lib-structure.yaml


|-- 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
|               |-- SDK.java       # 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 java.net.HttpClient. 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.

Parameters

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.

Errors

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.

Coming Soon

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