Create Unity SDKs from OpenAPI / Swagger

Unity SDK Overview

Speakeasy's Unity C# SDK is designed to support Unity LTS version 2021.3 and above.

The SDK is designed to be strongly typed, light on external dependencies, easy to debug, and easy to use.

Some of the core features of the SDK include:

Interfaces provided for the SDK's core components, allowing for dependency injection and mocking
C# Doc Comments generated from the OpenAPI document enhancing the intellisense and developer experience of using the SDK
Aysnc/Await support for all API calls that can be easily wrapped in Coroutines if needed
Optional Pagination support for supported APIs
Support for complex number types:
- System.Numbers.BigInteger
- System.Decimal
Support for both string and integer based enums
Streaming downloads for files

The SDK includes minimal dependencies, with the only external dependencies being:

newtonsoft.json - for JSON serialization/deserialization
and the UnityEngine libraries

Unity Package Structure

lib-structure.yaml


├── {SDK Class Name}             # The root namespace for the SDK where {SDK Class Name} is the provided name of the SDK
|   ├── {SDK Class Name}.csproj  
|   ├── {SDK Class Name}SDK.cs   # The main SDK class
|   ├── ...                      # Other SDK classes
|   ├── Models                   # The namespace for the SDK's models
|   |   ├── Operations           # The namespace for the SDK's operations models which generally house the request/response models for each API
|   |   |   ├── ... 
|   |   └── Shared               # The namespace for the SDK's models generated from components in the OpenAPI document
|   |       ├── ...
|   └── Utils                    # The namespace for the SDK's utility classes
├── docs                         # Markdown files for the SDK's documentation
|   └── ...
├── {SDK Class Name}.sln         # The SDK's solution file
└── ...

HTTP Client

The Unity C# SDK provides an interface for the HTTP Client used to make API calls. Allowing a custom HTTP Client to be provided to the SDK as long as it conforms to the interface.


public interface ISpeakeasyHttpClient
{
    void AddHeader(string key, string value);
    void AddQueryParam(string key, string value);
    Task<UnityWebRequest> SendAsync(UnityWebRequest message);
}

By default, the SDK will instantiate its own client using UnityWebRequest.SendWebRequest() to send the request, but this can be overridden by providing a custom implementation of the ISpeakeasyHttpClient interface:


var client = new CustomHttpClient();
var sdkInstance = new SDK(client);

This can be useful for example, if you want to use a custom HTTP Client that supports UnityWebRequests and supports a proxy or other custom configuration, or to provide a client preconfigured with standard headers as an example.

Data Types & Classes

Where possible, the C# SDK uses as many native types from the standard library as possible, for example:

string
System.DateTime
int
long
System.Numberics.BigInteger
float
double
decimal
bool
etc...

Only falling back on custom types when the native types are not suitable, for example:

A custom DateOnly class for date types
Custom enum types for string and integer based enums

For classes we generate standard C# classes with public fields that use Attributes for guiding the serialization/deserialization process.

The classes are also Serializable with [SerializeField] attributes on the fields to allow for use in the Unity Inspector.

Parameters

If configured, we will generate methods with parameters for each of the parameters defined in the OpenAPI document, as long as the number of parameters is less than or equal to the configured maxMethodParams value in the gen.yaml file.

If the number of parameters exceeds the configured maxMethodParams value or this is set to 0 then a request object is generated for the method instead that allows for all parameters to be passed in a single object.

Async Support

The Unity C# SDK is generated with async/await support for all API calls that can be easily wrapped in Coroutines if needed.

This can be done similarly to the below examples:


using System;
using System.Collections.Generic;
using System.Collections;
using System.IO;
using System.Threading.Tasks;
// Static methods that help using the SDK in Unity Coroutines
public static class CoroutineHelper
{
    public static IEnumerator Await(Task task)
    {
        while (!task.IsCompleted)
        {
            yield return null;
        }
        if (task.IsFaulted)
        {
            throw task.Exception;
        }
    }
    public static IEnumerator Await(Func<Task> taskDelegate)
    {
        return Await(taskDelegate.Invoke());
    }
}

and used like so:


yield return CoroutineHelper.Await(async () =>
{
    var sdk = new SDK();
    using (
        var res = await sdk.SomeMethod(...)
    )
    {
        // Handle response
    }
});

Due to the nature of the underlying UnityWebRequest the response is also a IDisposable object that should be disposed of when finished with or used within a using statement as shown above.

Errors

The Unity C# SDK will throw Exceptions for any network or invalid request errors.

For non-successful responses the SDK will return a response object that contains the status code and the response body, that can be checked for the status of the method call.

Coming Soon

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

User Agent Strings

The Unity SDK will include a user agent (opens in a new tab) string in all requests. This can be leveraged for tracking SDK usage amongst broader API usage. The format is as follows:


speakeasy-sdk/unity {{SDKVersion}} {{GenVersion}} {{DocVersion}} {{PackageName}}

Where

SDKVersion is the version of the SDK, defined in gen.yaml and released
GenVersion is the version of the Speakeasy generator
DocVersion is the version of the OpenAPI document
PackageName is the name of the package defined in gen.yaml