Generate SDKs from Swagger/OpenAPI specifications

This topic explains how to generate client SDKs from the OpenAPI (Swagger) specifications available in this partner preview. While pre-built SDKs are not provided for the partner preview, your own can easily be created using open-source tools.

SDKs (Software Development Kits) provide significant advantages when working with APIs:

Improved developer experience

• Type safety: Auto-generated classes and methods provide compiler validation, reducing runtime errors.

• Code completion: IDEs can offer suggestions and auto-completion for API operations.

• Documentation: SDK methods typically include helpful comments from the OpenAPI specs.

Reduced development time

• Pre-built request building: No manual construction of HTTP requests and URL paths.

• Serialization/deserialization: Automatic conversion between JSON responses and native objects.

More robust applications

• Consistent error handling: Standardized approach to API errors.

• Retry logic: Can incorporate intelligent retry patterns for transient failures.

• Validation: Client-side validation of inputs before sending requests.

By generating an SDK from our OpenAPI definitions, you'll significantly accelerate your development process while building more reliable applications against our APIs.

Important note on authentication

The generated SDKs do not include authentication libraries. For authentication and obtaining access tokens, Duende libraries are recommended. You'll need to integrate these authentication components separately from your SDK generation process. For more information, see Get an access token using client credential clients.

Recommended approach: Microsoft Kiota

Microsoft Kiota is recommended for generating client SDKs from our OpenAPI specifications, especially for .NET/C# applications.

Why Kiota?

• Official Microsoft tool for SDK generation.

• Strong support for .NET/C# applications.

• Produces clean, idiomatic code.

• Actively maintained.

• Supports multiple languages (.NET, Java, TypeScript, Python, Go, PHP, Ruby).

Using Kiota

1. Install Kiota. For full installation documentation, see the Microsoft document Install Kiota.

   # .NET Global Tool installation

   dotnet tool install --global Microsoft.OpenApi.Kiota

   Alternative installation methods:

   # Using npm

   npm i -g @microsoft/kiota

   # Manual download from GitHub releases

   # Visit: https://github.com/microsoft/kiota/releases

2. Download the OpenAPI specifications that you want to generate into SDKs.

   Download link example

   

3. Generate your SDK. For full usage examples, see the Microsoft document Using the Kiota tool.

   kiota generate \

   --openapi ./path/to/service-api.json \

   --language csharp \

   --output ./path/to/output \

   --namespace-name Your.Namespace

4. Include the generated code in your project and start using it.

Example: Generate an SDK for an API

kiota generate \

--openapi ./api-docs/accessmgmt-api-accountserviceinstance/v1.json \

--language csharp \

--output ./InstanceManagementClient \

--namespace-name MyCompany.Connect.InstanceManagement

Alternative tools

If Kiota doesn't meet your needs, consider these alternatives:

• OpenAPI Generator: A community-driven tool supporting many programming languages.

• Swagger Codegen: One of the original SDK generators for OpenAPI/Swagger.

Tips for SDK generation

• Validate OpenAPI specifications: Before generation to avoid errors.

• Consider authentication mechanisms: When implementing your client.

• Review generated code: For correctness.

• Keep your OpenAPI files updated: To ensure compatibility.