Generate C# SDKs from OpenAPI / Swagger

SDK Overview

Speakeasy's C# SDK is designed to support the .NET Ecosystem with support for .NET 5.X and above (The .NET version to build against is configurable).

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
  • Optional Pagination support for supported APIs
  • Support for complex number types:
    • System.Numbers.BigInteger
    • System.Decimal
  • Support for both string and integer based enums

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

  • newtonsoft.json - for JSON serialization/deserialization
  • nodatime - for date/time handling

C# Package Structure


├── {PackageName} # The root namespace for the SDK, based upon {PackageName} (`.`s in {PackageName} will become folders in the namespace)
| ├── {SDK Class Name}.csproj
| ├── {SDK Class Name}SDK.cs # The main SDK class
| ├── ... # Other SDK classes
| ├── Models # The namespace for the SDK's models
| | ├── Requests # The namespace for the SDK's request models which generally house the request/response models for each API (in older generations and in other targets, this folder was called `Operations`)
| | | ├── ...
| | └── Components # The namespace for the SDK's models generated from components in the OpenAPI document (in older generations, this folder was called `Shared`)
| | ├── ...
| └── 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 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<HttpResponseMessage> SendAsync(HttpRequestMessage message);

By default the SDK will instantiate its own client using the HttpClient class from the System.Net.Http namespace, but this can be overridden by providing a custom implementation of the ISpeakeasyHttpClient interface:

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

This can be useful for example if you want to use a custom HTTP Client that 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:

  • NodaTime.LocalDate 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.


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.


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

For unsuccesful responses, if a custom error response is specified in your spec file, the sdk will unmarshall the http response details into the custom error response, which will be then thrown as an Exception. When no custom response is specified in your spec, the SDK will throw an SDKException containing details of the failed response.

using Openapi;
using Openapi.Models.Shared;
using System;
using Openapi.Models.Errors;
using Openapi.Models.Operations;
var sdk = new SDK();
var res = await sdk.Errors.StatusGetXSpeakeasyErrorsAsync(statusCode: 385913);
// handle success
catch (Exception ex)
if (ex is StatusGetXSpeakeasyErrorsResponseBody)
// handle custom exception response
else if (ex is Openapi.Models.Errors.SDKException)
// handle standard exception response

User Agent Strings

The C# 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/csharp {{SDKVersion}} {{GenVersion}} {{DocVersion}} {{PackageName}}


  • 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