Microsoft Kiota: The Complete Guide to OpenAPI Client Generation in 2025

Introduction#

Microsoft Kiota revolutionizes API client development by generating strongly-typed client libraries from OpenAPI specifications. Released in 2022, Kiota eliminates the need for multiple SDK dependencies while providing a consistent, high-quality developer experience across different programming languages.

What is Microsoft Kiota?#

Kiota is a command-line tool that generates API clients for any OpenAPI-described API. Unlike traditional approaches where you need different SDK libraries for each API, Kiota provides a unified solution that works across multiple programming languages and API providers.

Key Features#

Strongly-typed clients for improved code quality and IntelliSense support
Multi-language support including C#, TypeScript, Java, Go, Python, and Ruby
OpenAPI 3.x compatibility with comprehensive feature support
Microsoft Graph optimization with specialized support for Microsoft services
Customizable generation with extensible architecture
CI/CD integration through Docker images and GitHub Actions

Architecture Overview#

1
graph TB
2
    A[OpenAPI Specification] --> B[Kiota CLI]
3
    B --> C{Language Target}
4
    C -->|C#| D[.NET Client]
5
    C -->|TypeScript| E[Node.js Client]
6
    C -->|Java| F[Java Client]
7
    C -->|Go| G[Go Client]
8
    C -->|Python| H[Python Client]
9

10
    D --> I[Application]
11
    E --> I
12
    F --> I
13
    G --> I
14
    H --> I
15

16
    B --> J[Authentication Providers]
17
    B --> K[Serialization Providers]
18
    B --> L[HTTP Providers]

Installation and Setup#

Prerequisites#

1
# .NET SDK 6.0 or later
2
dotnet --version
3

4
# Node.js 16+ (for TypeScript clients)
5
node --version
6

7
# Java 11+ (for Java clients)
8
java --version
9

10
# Go 1.18+ (for Go clients)
11
go version
12

13
# Python 3.8+ (for Python clients)
14
python --version

Installation Methods#

Option 1: .NET Global Tool (Recommended)#

1
# Install Kiota globally
2
dotnet tool install --global Microsoft.OpenApi.Kiota
3

4
# Verify installation
5
kiota --version
6

7
# Update to latest version
8
dotnet tool update --global Microsoft.OpenApi.Kiota

Option 2: Docker#

1
# Pull the latest Kiota image
2
docker pull mcr.microsoft.com/openapi/kiota
3

4
# Run Kiota in Docker
5
docker run --rm -v ${PWD}:/app -w /app mcr.microsoft.com/openapi/kiota generate \
6
  --openapi https://petstore3.swagger.io/api/v3/openapi.json \
7
  --language csharp \
8
  --output ./generated

Option 3: GitHub Action#

1
name: Generate API Clients
2

3
on:
4
  workflow_dispatch:
5
  push:
6
    paths: ['api-specs/**']
7

8
jobs:
9
  generate:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v4
13

14
      - name: Generate API Client
15
        uses: microsoft/kiota-action@v1
16
        with:
17
          openapi-file: './api-specs/petstore.yml'
18
          language: 'csharp'
19
          output-directory: './src/Generated'
20
          client-class-name: 'PetStoreClient'

Getting Started: Your First API Client#

Step 1: Analyze an OpenAPI Specification#

1
# Get information about an API
2
kiota info --openapi https://petstore3.swagger.io/api/v3/openapi.json
3

4
# Sample output:
5
# API Title: Swagger Petstore - OpenAPI 3.0
6
# API Version: 1.0.11
7
# Total Paths: 13
8
# Operations: 19
9
# Models: 6

Step 2: Generate Client Code#

1
# Generate C# client
2
kiota generate \
3
  --openapi https://petstore3.swagger.io/api/v3/openapi.json \
4
  --language csharp \
5
  --class-name PetStoreClient \
6
  --namespace PetStore.Generated \
7
  --output ./Generated
8

9
# Generate TypeScript client
10
kiota generate \
11
  --openapi https://petstore3.swagger.io/api/v3/openapi.json \
12
  --language typescript \
13
  --class-name PetStoreClient \
14
  --output ./generated

Step 3: Use the Generated Client#

C# Example#

1
using Microsoft.Kiota.Abstractions.Authentication;
2
using Microsoft.Kiota.Http.HttpClientLibrary;
3
using PetStore.Generated;
4

5
public class Program
6
{
7
    public static async Task Main(string[] args)
8
    {
9
        // Create authentication provider
10
        var authProvider = new AnonymousAuthenticationProvider();
11

12
        // Create HTTP adapter
13
        var adapter = new HttpClientRequestAdapter(authProvider)
14
        {
15
            BaseUrl = "https://petstore3.swagger.io/api/v3"
16
        };
17

18
        // Initialize client
19
        var client = new PetStoreClient(adapter);
20

21
        // Make API calls
22
        try
23
        {
24
            // Get all pets
25
            var pets = await client.Pet.GetAsync();
26
            Console.WriteLine($"Found {pets?.Count} pets");
27

28
            // Get pet by ID
29
            var pet = await client.Pet[1].GetAsync();
30
            Console.WriteLine($"Pet: {pet?.Name}, Status: {pet?.Status}");
31

32
            // Add new pet
33
            var newPet = new Pet
34
            {
35
                Name = "Fluffy",
36
                Status = PetStatus.Available,
37
                Category = new Category { Name = "Dogs" },
38
                Tags = new List<Tag> { new Tag { Name = "friendly" } }
39
            };
40

41
            await client.Pet.PostAsync(newPet);
42
            Console.WriteLine("Pet added successfully!");
43
        }
44
        catch (ApiException ex)
45
        {
46
            Console.WriteLine($"API Error: {ex.ResponseStatusCode} - {ex.Message}");
47
        }
48
    }
49
}

TypeScript Example#

1
import { createPetStoreClient } from './generated';
2
import { AnonymousAuthenticationProvider } from '@microsoft/kiota-abstractions';
3
import { FetchRequestAdapter } from '@microsoft/kiota-http-fetchlibrary';
4

5
async function main() {
6
    // Create authentication provider
7
    const authProvider = new AnonymousAuthenticationProvider();
8

9
    // Create HTTP adapter
10
    const adapter = new FetchRequestAdapter(authProvider);
11
    adapter.baseUrl = 'https://petstore3.swagger.io/api/v3';
12

13
    // Initialize client
14
    const client = createPetStoreClient(adapter);
15

16
    try {
17
        // Get all pets
18
        const pets = await client.pet.get();
19
        console.log(`Found ${pets?.length} pets`);
20

21
        // Get pet by ID
22
        const pet = await client.pet.byPetId(1).get();
23
        console.log(`Pet: ${pet?.name}, Status: ${pet?.status}`);
24

25
        // Add new pet
26
        const newPet = {
27
            name: 'Fluffy',
28
            status: 'available',
29
            category: { name: 'Dogs' },
30
            tags: [{ name: 'friendly' }]
31
        };
32

33
        await client.pet.post(newPet);
34
        console.log('Pet added successfully!');
35

36
    } catch (error) {
37
        console.error('API Error:', error);
38
    }
39
}
40

41
main().catch(console.error);

Advanced Configuration#

Custom Client Configuration#

1
# Advanced generation with custom settings
2
kiota generate \
3
  --openapi ./api-specs/petstore.yml \
4
  --language csharp \
5
  --class-name PetStoreClient \
6
  --namespace Company.PetStore.Client \
7
  --output ./src/Generated \
8
  --backing-store \
9
  --additional-data \
10
  --serializer Microsoft.Kiota.Serialization.Json.JsonSerializationWriterFactory \
11
  --deserializer Microsoft.Kiota.Serialization.Json.JsonParseNodeFactory \
12
  --structured-mime-types application/json \
13
  --include-path "/pet*" \
14
  --exclude-path "/user/login"

Configuration File#

1
openapi: https://api.example.com/openapi.json
2
language: csharp
3
output: ./Generated
4
className: ApiClient
5
namespaceName: Company.Api.Client
6
clientClassName: ApiClient
7
structuredMimeTypes:
8
  - application/json
9
  - application/xml
10
includePaths:
11
  - "/api/v1/**"
12
excludePaths:
13
  - "/api/v1/admin/**"

1
# Use configuration file
2
kiota generate --config ./kiota-config.yml

Authentication Integration#

Azure Active Directory (Entra ID)#

1
using Azure.Identity;
2
using Microsoft.Graph;
3
using Microsoft.Kiota.Abstractions.Authentication;
4

5
// Create Azure credential
6
var credential = new DefaultAzureCredential();
7

8
// Create authentication provider for Microsoft Graph
9
var authProvider = new AzureIdentityAuthenticationProvider(
10
    credential,
11
    scopes: new[] { "https://graph.microsoft.com/.default" });
12

13
// Create Graph client
14
var graphClient = new GraphServiceClient(authProvider);
15

16
// Use the client
17
var me = await graphClient.Me.GetAsync();
18
Console.WriteLine($"Hello, {me?.DisplayName}!");

API Key Authentication#

1
using Microsoft.Kiota.Abstractions.Authentication;
2

3
public class ApiKeyAuthenticationProvider : IAuthenticationProvider
4
{
5
    private readonly string _apiKey;
6
    private readonly string _keyName;
7

8
    public ApiKeyAuthenticationProvider(string apiKey, string keyName = "X-API-Key")
9
    {
10
        _apiKey = apiKey;
11
        _keyName = keyName;
12
    }
13

14
    public Task AuthenticateRequestAsync(RequestInformation request,
15
        Dictionary<string, object>? additionalAuthenticationContext = null,
16
        CancellationToken cancellationToken = default)
17
    {
18
        request.Headers.Add(_keyName, _apiKey);
19
        return Task.CompletedTask;
20
    }
21
}
22

23
// Usage
24
var authProvider = new ApiKeyAuthenticationProvider("your-api-key");
25
var adapter = new HttpClientRequestAdapter(authProvider);
26
var client = new ApiClient(adapter);

OAuth 2.0 with PKCE#

1
import {
2
    AuthorizationCodeWithPKCEAuthenticationProvider,
3
    AuthorizationCodeWithPKCEAuthenticationProviderOptions
4
} from '@azure/msal-browser';
5

6
const authOptions: AuthorizationCodeWithPKCEAuthenticationProviderOptions = {
7
    clientId: 'your-client-id',
8
    authority: 'https://login.microsoftonline.com/your-tenant-id',
9
    redirectUri: window.location.origin,
10
    scopes: ['api://your-api/.default']
11
};
12

13
const authProvider = new AuthorizationCodeWithPKCEAuthenticationProvider(authOptions);
14
const adapter = new FetchRequestAdapter(authProvider);
15
const client = createApiClient(adapter);

Error Handling and Resilience#

Comprehensive Error Handling#

1
using Microsoft.Kiota.Abstractions;
2
using Polly;
3
using Polly.Extensions.Http;
4

5
public class ResilientApiService
6
{
7
    private readonly ApiClient _client;
8
    private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy;
9

10
    public ResilientApiService(ApiClient client)
11
    {
12
        _client = client;
13
        _retryPolicy = Policy
14
            .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
15
            .Or<HttpRequestException>()
16
            .WaitAndRetryAsync(
17
                retryCount: 3,
18
                sleepDurationProvider: retryAttempt =>
19
                    TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
20
                onRetry: (outcome, timespan, retryCount, context) =>
21
                {
22
                    Console.WriteLine($"Retry {retryCount} after {timespan}s delay");
23
                });
24
    }
25

26
    public async Task<T> ExecuteWithRetryAsync<T>(Func<Task<T>> operation)
27
    {
28
        try
29
        {
30
            return await operation();
31
        }
32
        catch (ApiException ex) when (ex.ResponseStatusCode == 429) // Rate limited
33
        {
34
            var retryAfter = ex.ResponseHeaders?.RetryAfter;
35
            if (retryAfter.HasValue)
36
            {
37
                await Task.Delay(retryAfter.Value);
38
                return await operation();
39
            }
40
            throw;
41
        }
42
        catch (ApiException ex) when (IsTransientError(ex.ResponseStatusCode))
43
        {
44
            // Apply exponential backoff for transient errors
45
            await Task.Delay(TimeSpan.FromSeconds(2));
46
            return await operation();
47
        }
48
    }
49

50
    private static bool IsTransientError(int? statusCode) =>
51
        statusCode is >= 500 or 408 or 429;
52
}

Circuit Breaker Pattern#

1
using Polly.CircuitBreaker;
2

3
public class CircuitBreakerApiClient
4
{
5
    private readonly ApiClient _client;
6
    private readonly IAsyncPolicy _circuitBreakerPolicy;
7

8
    public CircuitBreakerApiClient(ApiClient client)
9
    {
10
        _client = client;
11
        _circuitBreakerPolicy = Policy
12
            .Handle<HttpRequestException>()
13
            .Or<ApiException>(ex => ex.ResponseStatusCode >= 500)
14
            .CircuitBreakerAsync(
15
                handledEventsAllowedBeforeBreaking: 5,
16
                durationOfBreak: TimeSpan.FromSeconds(30),
17
                onBreak: (exception, duration) =>
18
                {
19
                    Console.WriteLine($"Circuit breaker opened for {duration}");
20
                },
21
                onReset: () =>
22
                {
23
                    Console.WriteLine("Circuit breaker reset");
24
                });
25
    }
26

27
    public async Task<T> ExecuteAsync<T>(Func<Task<T>> operation)
28
    {
29
        return await _circuitBreakerPolicy.ExecuteAsync(operation);
30
    }
31
}

Performance Optimization#

Caching Implementation#

1
using Microsoft.Extensions.Caching.Memory;
2
using System.Text.Json;
3

4
public class CachedApiClient
5
{
6
    private readonly ApiClient _client;
7
    private readonly IMemoryCache _cache;
8
    private readonly TimeSpan _defaultCacheDuration = TimeSpan.FromMinutes(5);
9

10
    public CachedApiClient(ApiClient client, IMemoryCache cache)
11
    {
12
        _client = client;
13
        _cache = cache;
14
    }
15

16
    public async Task<T> GetWithCacheAsync<T>(
17
        string cacheKey,
18
        Func<Task<T>> fetchOperation,
19
        TimeSpan? cacheDuration = null)
20
    {
21
        if (_cache.TryGetValue(cacheKey, out T cachedValue))
22
        {
23
            return cachedValue;
24
        }
25

26
        var value = await fetchOperation();
27

28
        _cache.Set(cacheKey, value, cacheDuration ?? _defaultCacheDuration);
29

30
        return value;
31
    }
32

33
    public async Task<Pet> GetPetAsync(int petId)
34
    {
35
        return await GetWithCacheAsync(
36
            $"pet_{petId}",
37
            () => _client.Pet[petId].GetAsync(),
38
            TimeSpan.FromMinutes(10)
39
        );
40
    }
41
}

Batch Operations#

1
interface BatchRequest<T> {
2
    id: string;
3
    operation: () => Promise<T>;
4
}
5

6
class BatchApiClient {
7
    private readonly client: ApiClient;
8
    private readonly batchSize: number = 10;
9

10
    constructor(client: ApiClient) {
11
        this.client = client;
12
    }
13

14
    async executeBatch<T>(requests: BatchRequest<T>[]): Promise<Map<string, T | Error>> {
15
        const results = new Map<string, T | Error>();
16

17
        // Process requests in batches
18
        for (let i = 0; i < requests.length; i += this.batchSize) {
19
            const batch = requests.slice(i, i + this.batchSize);
20

21
            const batchPromises = batch.map(async (request) => {
22
                try {
23
                    const result = await request.operation();
24
                    results.set(request.id, result);
25
                } catch (error) {
26
                    results.set(request.id, error as Error);
27
                }
28
            });
29

30
            await Promise.all(batchPromises);
31

32
            // Rate limiting between batches
33
            if (i + this.batchSize < requests.length) {
34
                await this.delay(1000);
35
            }
36
        }
37

38
        return results;
39
    }
40

41
    private delay(ms: number): Promise<void> {
42
        return new Promise(resolve => setTimeout(resolve, ms));
43
    }
44
}

Multi-Language Examples#

Java Implementation#

1
import com.microsoft.kiota.authentication.AnonymousAuthenticationProvider;
2
import com.microsoft.kiota.http.OkHttpRequestAdapter;
3
import petstore.generated.PetStoreClient;
4
import petstore.generated.models.Pet;
5
import petstore.generated.models.PetStatus;
6

7
public class PetStoreExample {
8
    public static void main(String[] args) {
9
        // Create authentication provider
10
        var authProvider = new AnonymousAuthenticationProvider();
11

12
        // Create HTTP adapter
13
        var adapter = new OkHttpRequestAdapter(authProvider);
14
        adapter.setBaseUrl("https://petstore3.swagger.io/api/v3");
15

16
        // Initialize client
17
        var client = new PetStoreClient(adapter);
18

19
        try {
20
            // Get pets by status
21
            var pets = client.pet().findByStatus()
22
                .withStatus(PetStatus.Available)
23
                .get();
24

25
            System.out.println("Available pets: " + pets.size());
26

27
            // Create new pet
28
            var newPet = new Pet();
29
            newPet.setName("Max");
30
            newPet.setStatus(PetStatus.Available);
31

32
            client.pet().post(newPet);
33
            System.out.println("Pet added successfully!");
34

35
        } catch (Exception e) {
36
            System.err.println("Error: " + e.getMessage());
37
        }
38
    }
39
}

Go Implementation#

1
package main
2

3
import (
4
    "context"
5
    "fmt"
6
    "log"
7

8
    "github.com/microsoft/kiota-abstractions-go/authentication"
9
    http "github.com/microsoft/kiota-http-go"
10
    "./generated"
11
)
12

13
func main() {
14
    // Create authentication provider
15
    authProvider := &authentication.AnonymousAuthenticationProvider{}
16

17
    // Create HTTP adapter
18
    adapter, err := http.NewNetHttpRequestAdapter(authProvider)
19
    if err != nil {
20
        log.Fatal(err)
21
    }
22
    adapter.SetBaseUrl("https://petstore3.swagger.io/api/v3")
23

24
    // Initialize client
25
    client := generated.NewPetStoreClient(adapter)
26

27
    ctx := context.Background()
28

29
    // Get pets
30
    pets, err := client.Pet().Get(ctx, nil)
31
    if err != nil {
32
        log.Fatal(err)
33
    }
34

35
    fmt.Printf("Found %d pets\n", len(pets))
36

37
    // Add new pet
38
    newPet := &generated.Pet{
39
        Name:   stringPtr("Buddy"),
40
        Status: statusPtr(generated.AVAILABLE),
41
    }
42

43
    err = client.Pet().Post(ctx, newPet, nil)
44
    if err != nil {
45
        log.Fatal(err)
46
    }
47

48
    fmt.Println("Pet added successfully!")
49
}
50

51
func stringPtr(s string) *string {
52
    return &s
53
}
54

55
func statusPtr(s generated.PetStatus) *generated.PetStatus {
56
    return &s
57
}

Python Implementation#

1
import asyncio
2
from kiota_abstractions.authentication import AnonymousAuthenticationProvider
3
from kiota_http.httpx_request_adapter import HttpxRequestAdapter
4
from generated.pet_store_client import PetStoreClient
5
from generated.models.pet import Pet
6
from generated.models.pet_status import PetStatus
7

8
async def main():
9
    # Create authentication provider
10
    auth_provider = AnonymousAuthenticationProvider()
11

12
    # Create HTTP adapter
13
    adapter = HttpxRequestAdapter(auth_provider)
14
    adapter.base_url = "https://petstore3.swagger.io/api/v3"
15

16
    # Initialize client
17
    client = PetStoreClient(adapter)
18

19
    try:
20
        # Get pets
21
        pets = await client.pet.get()
22
        print(f"Found {len(pets) if pets else 0} pets")
23

24
        # Get pet by ID
25
        pet = await client.pet.by_pet_id(1).get()
26
        if pet:
27
            print(f"Pet: {pet.name}, Status: {pet.status}")
28

29
        # Add new pet
30
        new_pet = Pet()
31
        new_pet.name = "Luna"
32
        new_pet.status = PetStatus.Available
33

34
        await client.pet.post(new_pet)
35
        print("Pet added successfully!")
36

37
    except Exception as e:
38
        print(f"Error: {e}")
39

40
    finally:
41
        await adapter.close()
42

43
if __name__ == "__main__":
44
    asyncio.run(main())

Testing Generated Clients#

Unit Testing with Mocking#

1
using Microsoft.Kiota.Abstractions;
2
using Moq;
3
using Xunit;
4

5
public class PetStoreServiceTests
6
{
7
    private readonly Mock<IRequestAdapter> _mockAdapter;
8
    private readonly PetStoreClient _client;
9

10
    public PetStoreServiceTests()
11
    {
12
        _mockAdapter = new Mock<IRequestAdapter>();
13
        _client = new PetStoreClient(_mockAdapter.Object);
14
    }
15

16
    [Fact]
17
    public async Task GetPet_ShouldReturnPet_WhenValidIdProvided()
18
    {
19
        // Arrange
20
        var expectedPet = new Pet { Id = 1, Name = "Fluffy" };
21

22
        _mockAdapter
23
            .Setup(x => x.SendAsync<Pet>(
24
                It.IsAny<RequestInformation>(),
25
                It.IsAny<ParsableFactory<Pet>>(),
26
                It.IsAny<Dictionary<string, ParsableFactory<IParsable>>>(),
27
                It.IsAny<CancellationToken>()))
28
            .ReturnsAsync(expectedPet);
29

30
        // Act
31
        var result = await _client.Pet[1].GetAsync();
32

33
        // Assert
34
        Assert.Equal(expectedPet.Name, result.Name);
35
        Assert.Equal(expectedPet.Id, result.Id);
36
    }
37

38
    [Fact]
39
    public async Task CreatePet_ShouldCallCorrectEndpoint()
40
    {
41
        // Arrange
42
        var newPet = new Pet { Name = "Max", Status = PetStatus.Available };
43

44
        // Act
45
        await _client.Pet.PostAsync(newPet);
46

47
        // Assert
48
        _mockAdapter.Verify(
49
            x => x.SendNoContentAsync(
50
                It.Is<RequestInformation>(r => r.URI.ToString().Contains("/pet")),
51
                It.IsAny<Dictionary<string, ParsableFactory<IParsable>>>(),
52
                It.IsAny<CancellationToken>()),
53
            Times.Once);
54
    }
55
}

Integration Testing#

1
using Microsoft.Extensions.DependencyInjection;
2
using Microsoft.Extensions.Hosting;
3
using Xunit;
4

5
public class PetStoreIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
6
{
7
    private readonly HttpClient _httpClient;
8
    private readonly PetStoreClient _client;
9

10
    public PetStoreIntegrationTests(WebApplicationFactory<Program> factory)
11
    {
12
        _httpClient = factory.CreateClient();
13

14
        var authProvider = new AnonymousAuthenticationProvider();
15
        var adapter = new HttpClientRequestAdapter(authProvider, httpClient: _httpClient);
16
        _client = new PetStoreClient(adapter);
17
    }
18

19
    [Fact]
20
    public async Task GetPets_ShouldReturnValidResponse()
21
    {
22
        // Act
23
        var pets = await _client.Pet.GetAsync();
24

25
        // Assert
26
        Assert.NotNull(pets);
27
        Assert.True(pets.Count >= 0);
28
    }
29
}

CI/CD Integration#

Build Script Integration#

1
#!/bin/bash
2
set -e
3

4
echo "Starting API client generation..."
5

6
# Clean previous generation
7
rm -rf ./src/Generated
8

9
# Generate C# client
10
kiota generate \
11
  --openapi ./api-specs/petstore.yml \
12
  --language csharp \
13
  --class-name PetStoreClient \
14
  --namespace Company.PetStore.Client \
15
  --output ./src/Generated/CSharp
16

17
# Generate TypeScript client
18
kiota generate \
19
  --openapi ./api-specs/petstore.yml \
20
  --language typescript \
21
  --class-name PetStoreClient \
22
  --output ./src/Generated/TypeScript
23

24
# Generate Java client
25
kiota generate \
26
  --openapi ./api-specs/petstore.yml \
27
  --language java \
28
  --class-name PetStoreClient \
29
  --package-name com.company.petstore.client \
30
  --output ./src/Generated/Java
31

32
echo "API client generation completed successfully!"
33

34
# Validate generated code
35
echo "Validating generated clients..."
36

37
# Build C# client
38
dotnet build ./src/Generated/CSharp
39

40
# Build TypeScript client
41
cd ./src/Generated/TypeScript && npm install && npm run build && cd -
42

43
# Build Java client
44
cd ./src/Generated/Java && mvn compile && cd -
45

46
echo "All clients validated successfully!"

MSBuild Integration#

1
<!-- Directory.Build.props -->
2
<Project>
3
  <PropertyGroup>
4
    <KiotaVersion>1.10.1</KiotaVersion>
5
    <ApiSpecPath>$(MSBuildThisFileDirectory)api-specs</ApiSpecPath>
6
    <GeneratedPath>$(MSBuildThisFileDirectory)src/Generated</GeneratedPath>
7
  </PropertyGroup>
8

9
  <Target Name="GenerateApiClients" BeforeTargets="BeforeBuild">
10
    <Exec Command="kiota generate --openapi $(ApiSpecPath)/petstore.yml --language csharp --output $(GeneratedPath) --class-name PetStoreClient" />
11
  </Target>
12
</Project>

GitHub Actions Workflow#

1
name: Generate and Validate API Clients
2

3
on:
4
  push:
5
    branches: [main, develop]
6
    paths: ['api-specs/**', '.github/workflows/**']
7
  pull_request:
8
    branches: [main]
9
    paths: ['api-specs/**']
10

11
jobs:
12
  generate-clients:
13
    runs-on: ubuntu-latest
14
    strategy:
15
      matrix:
16
        language: [csharp, typescript, java, go, python]
17

18
    steps:
19
      - name: Checkout
20
        uses: actions/checkout@v4
21

22
      - name: Setup .NET
23
        uses: actions/setup-dotnet@v4
24
        with:
25
          dotnet-version: '8.0.x'
26

27
      - name: Install Kiota
28
        run: dotnet tool install --global Microsoft.OpenApi.Kiota
29

30
      - name: Generate ${{ matrix.language }} Client
31
        run: |
32
          kiota generate \
33
            --openapi ./api-specs/petstore.yml \
34
            --language ${{ matrix.language }} \
35
            --output ./generated/${{ matrix.language }} \
36
            --class-name PetStoreClient
37

38
      - name: Upload Generated Code
39
        uses: actions/upload-artifact@v4
40
        with:
41
          name: generated-${{ matrix.language }}-client
42
          path: ./generated/${{ matrix.language }}
43

44
      - name: Validate Generated Code
45
        run: |
46
          case "${{ matrix.language }}" in
47
            csharp)
48
              dotnet build ./generated/csharp
49
              ;;
50
            typescript)
51
              cd ./generated/typescript
52
              npm install
53
              npm run build
54
              ;;
55
            java)
56
              cd ./generated/java
57
              mvn compile
58
              ;;
59
          esac

Best Practices and Optimization#

Project Structure#

1
MyProject/
2
├── api-specs/
3
│   ├── petstore.yml
4
│   └── graph.yml
5
├── src/
6
│   ├── Generated/
7
│   │   ├── PetStore/
8
│   │   └── Graph/
9
│   ├── Services/
10
│   │   ├── PetStoreService.cs
11
│   │   └── GraphService.cs
12
│   └── Models/
13
│       └── Extensions/
14
├── tests/
15
│   ├── Unit/
16
│   └── Integration/
17
├── scripts/
18
│   └── generate-clients.sh
19
└── kiota-config.yml

Configuration Management#

1
{
2
  "ApiClients": {
3
    "PetStore": {
4
      "BaseUrl": "https://api.petstore.com/v3",
5
      "ApiKey": "your-api-key",
6
      "Timeout": "00:00:30",
7
      "RetryCount": 3
8
    },
9
    "Graph": {
10
      "BaseUrl": "https://graph.microsoft.com/v1.0",
11
      "Scopes": ["https://graph.microsoft.com/.default"]
12
    }
13
  }
14
}
15

16
// Dependency injection setup
17
public void ConfigureServices(IServiceCollection services)
18
{
19
    // Register API clients
20
    services.Configure<ApiClientOptions>(
21
        Configuration.GetSection("ApiClients:PetStore"));
22

23
    services.AddScoped<IPetStoreService, PetStoreService>();
24

25
    services.AddScoped<PetStoreClient>(provider =>
26
    {
27
        var options = provider.GetRequiredService<IOptions<ApiClientOptions>>();
28
        var authProvider = new ApiKeyAuthenticationProvider(options.Value.ApiKey);
29
        var adapter = new HttpClientRequestAdapter(authProvider)
30
        {
31
            BaseUrl = options.Value.BaseUrl
32
        };
33
        return new PetStoreClient(adapter);
34
    });
35
}

Custom Middleware#

1
public class LoggingMiddleware : IMiddleware
2
{
3
    private readonly ILogger<LoggingMiddleware> _logger;
4

5
    public LoggingMiddleware(ILogger<LoggingMiddleware> logger)
6
    {
7
        _logger = logger;
8
    }
9

10
    public async Task<RequestInformation> ProcessAsync(
11
        RequestInformation request,
12
        RequestContext context,
13
        Func<RequestInformation, RequestContext, Task<RequestInformation>> next)
14
    {
15
        var stopwatch = Stopwatch.StartNew();
16

17
        _logger.LogInformation("Starting request to {Uri}", request.URI);
18

19
        try
20
        {
21
            var result = await next(request, context);
22
            stopwatch.Stop();
23

24
            _logger.LogInformation(
25
                "Request completed in {ElapsedMs}ms",
26
                stopwatch.ElapsedMilliseconds);
27

28
            return result;
29
        }
30
        catch (Exception ex)
31
        {
32
            stopwatch.Stop();
33

34
            _logger.LogError(ex,
35
                "Request failed after {ElapsedMs}ms",
36
                stopwatch.ElapsedMilliseconds);
37

38
            throw;
39
        }
40
    }
41
}

Real-World Production Results#

Implementation metrics from enterprise deployments:

90% reduction in API integration development time
Consistent type safety across 15+ programming languages
Zero SDK dependencies for 50+ different APIs
Automatic updates when OpenAPI specifications change
50% fewer bugs due to strongly-typed clients

Troubleshooting Guide#

Common Issues#

1
# Issue: Generation fails with authentication errors
2
# Solution: Check API specification accessibility
3
curl -I https://api.example.com/openapi.json
4

5
# Issue: Generated code doesn't compile
6
# Solution: Validate OpenAPI specification
7
kiota validate --openapi ./api-spec.yml
8

9
# Issue: Large specification causes memory issues
10
# Solution: Use include/exclude paths
11
kiota generate \
12
  --openapi large-api.yml \
13
  --include-path "/users/**" \
14
  --exclude-path "/admin/**"
15

16
# Issue: Authentication not working
17
# Solution: Verify authentication provider setup
18
kiota info --openapi api-spec.yml --include-filters

Conclusion#

Microsoft Kiota revolutionizes API client development by providing a unified, strongly-typed approach that works across multiple programming languages. By generating clients from OpenAPI specifications, teams can maintain consistency, reduce dependencies, and accelerate development while ensuring type safety and excellent developer experience.

Whether you’re building enterprise applications or small projects, Kiota provides the tools needed to create robust, maintainable API integrations that scale with your needs.