Como usar o Kiota para gerar SDKs de API no .NET

O problema que o Kiota resolve

Em projetos que consomem dezenas de APIs, manter SDKs distintos vira um problema real. Afinal, cada biblioteca traz seu modelo de autenticação, sua forma de tratar erros, sua serialização e seus próprios ciclos de atualização.

Essa fragmentação aumenta o custo cognitivo da equipe e amplia a superfície de falhas do sistema. Além disso, cada nova API integrada exige aprender uma nova biblioteca do zero.

O Kiota propõe uma abordagem unificada: uma única ferramenta de linha de comando gera clientes para qualquer API que tenha uma descrição OpenAPI válida. Segundo a documentação oficial do Kiota, ele suporta C#, Go, Java, PHP, Python, Ruby e TypeScript.

O cliente gerado se apoia em uma biblioteca central leve, que fornece abstrações para autenticação, serialização e comunicação HTTP. Dessa forma, o Kiota no .NET minimiza dependências externas e padroniza o comportamento, independentemente da API consumida.

Como o Kiota no .NET funciona por dentro

A geração de código acontece em quatro estágios, orquestrados pelo componente KiotaBuilder. Entender esse pipeline ajuda a explicar por que o resultado é tão consistente entre linguagens.

Instalação do Kiota no .NET

O Kiota pode ser instalado de várias formas, e a mais direta é como ferramenta global do .NET:

dotnet tool install --global Microsoft.OpenApi.Kiota

Para ambientes sem o SDK do .NET, a Microsoft disponibiliza binários prontos para Linux (x64), macOS (arm64 e x64) e Windows (x86, x64 e arm64). Além disso, existe uma imagem Docker oficial:

docker run -v /some/output/path:/app/output \
-v /some/input/description.yml:/app/openapi.yaml \
mcr.microsoft.com/openapi/kiota generate --language csharp -n namespace-prefix

Também existe uma extensão para Visual Studio Code, em preview público, e uma action para o GitHub Actions, que automatiza a atualização dos clientes no pipeline.

Gerando um cliente com o Kiota no .NET

O fluxo básico consiste em apontar a ferramenta para uma descrição OpenAPI e informar a linguagem, o nome da classe, o namespace e o diretório de saída.

Como exemplo, o comando a seguir gera um cliente C# para um subconjunto da API do Microsoft Graph, filtrando apenas os endpoints do recurso To Do:

kiota generate \
  --openapi https://aka.ms/graph/v1.0/openapi.yaml \
  --include-path "/me/todo/**" \
  --language CSharp \
  --class-name TaskClient \
  --namespace-name MyTaskApp.Client \
  --output ./src/MyTaskApp/Client

O parâmetro --include-path é fundamental em APIs grandes como o Microsoft Graph. Com ele, o Kiota gera apenas os modelos e request builders das operações que a aplicação usa, o que reduz drasticamente o tamanho do código.

Junto com o código, o diretório de saída recebe um arquivo kiota-lock.json. Ele guarda os parâmetros da geração e um hash da descrição, e deve ir para o controle de versão junto com o cliente.

Se você mantém a sua própria API, vale gerar a descrição OpenAPI direto do projeto. O artigo sobre documentação de APIs com OpenAPI, Swagger e Scalar mostra esse lado do processo.

Usando o cliente gerado

Após a geração, o código depende de bibliotecas companion que fornecem o RequestAdapter, a autenticação e a serialização. Para C#, o pacote Microsoft.Kiota.Bundle reúne todos esses componentes:

dotnet add package Microsoft.Kiota.Bundle

Em projetos existentes, a documentação pede TargetFramework igual a netstandard2.0, netstandard2.1, net462 ou net8.0 em diante. Além disso, a Microsoft recomenda habilitar Nullable.

Com o Kiota no .NET, o uso do cliente segue sempre o mesmo padrão. Primeiro, você cria um RequestAdapter com o provedor de autenticação adequado e, depois, passa esse adapter ao cliente gerado.

O exemplo abaixo usa um cliente PostsClient, gerado a partir de uma descrição da API pública JSONPlaceholder:

using KiotaPosts.Client;
using KiotaPosts.Client.Models;
using Microsoft.Kiota.Abstractions.Authentication;
using Microsoft.Kiota.Http.HttpClientLibrary;

// A API não exige autenticação, então usamos o provedor anônimo
var authProvider = new AnonymousAuthenticationProvider();
var adapter = new HttpClientRequestAdapter(authProvider);
var client = new PostsClient(adapter);

// GET /posts
var allPosts = await client.Posts.GetAsync();

// POST /posts
var newPost = new Post
{
    UserId = 42,
    Title = "Testing Kiota-generated API client",
    Body = "Hello world!"
};
var createdPost = await client.Posts.PostAsync(newPost);

// PATCH /posts/{id}
var update = new Post { Title = "Updated title" };
var updatedPost = await client.Posts[5].PatchAsync(update);

// DELETE /posts/{id}
await client.Posts[5].DeleteAsync();

A navegação pela IDE é um dos diferenciais do cliente que o Kiota gera no .NET. O autocomplete expõe os recursos da API como propriedades em árvore, então você descobre endpoints sem consultar documentação externa.

Repare em client.Posts[5]: o indexador representa o segmento {id} da URL. Em outras palavras, o código espelha exatamente a estrutura dos caminhos da API.

Kiota no .NET com injeção de dependência

Em aplicações ASP.NET Core, o ideal é registrar o cliente do Kiota no contêiner de injeção de dependência do .NET. A Microsoft documenta esse cenário em um tutorial que usa a API do GitHub como exemplo.

Primeiro, você cria dois métodos de extensão no próprio projeto. Eles usam o KiotaClientFactory, da biblioteca HTTP do Kiota, para descobrir os handlers padrão e registrá-los:

using Microsoft.Kiota.Http.HttpClientLibrary;

public static class KiotaServiceCollectionExtensions
{
    public static IServiceCollection AddKiotaHandlers(this IServiceCollection services)
    {
        // Registra os handlers padrão do Kiota no contêiner
        var kiotaHandlers = KiotaClientFactory.GetDefaultHandlerActivatableTypes();
        foreach (var handler in kiotaHandlers)
            services.AddTransient(handler);

        return services;
    }

    public static IHttpClientBuilder AttachKiotaHandlers(this IHttpClientBuilder builder)
    {
        // Anexa os handlers ao pipeline do HttpClient, na ordem de execução
        var kiotaHandlers = KiotaClientFactory.GetDefaultHandlerActivatableTypes();
        foreach (var handler in kiotaHandlers)
            builder.AddHttpMessageHandler(sp => (DelegatingHandler)sp.GetRequiredService(handler));

        return builder;
    }
}

Em seguida, uma fábrica recebe o HttpClient gerenciado e cria o cliente gerado:

using GitHub.ApiClient;
using Microsoft.Kiota.Abstractions.Authentication;
using Microsoft.Kiota.Http.HttpClientLibrary;

public class GitHubClientFactory(HttpClient httpClient)
{
    private readonly IAuthenticationProvider _authenticationProvider = new AnonymousAuthenticationProvider();

    public GitHubClient GetClient() =>
        new(new HttpClientRequestAdapter(_authenticationProvider, httpClient: httpClient));
}

Por fim, o Program.cs registra tudo:

builder.Services.AddKiotaHandlers();

builder.Services.AddHttpClient<GitHubClientFactory>((sp, client) =>
{
    client.BaseAddress = new Uri("https://api.github.com");
    client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
}).AttachKiotaHandlers();

builder.Services.AddTransient(sp =>
    sp.GetRequiredService<GitHubClientFactory>().GetClient());

O método AttachKiotaHandlers() conecta os handlers do Kiota ao pipeline do HttpClient. Com isso, você ganha recursos como retry, redirecionamento e compressão.

Essa integração deixa o ciclo de vida do cliente sob controle do contêiner, alinhado às boas práticas do ASP.NET Core. Se quiser revisar os tempos de vida dos serviços, o artigo sobre AddTransient, AddScoped e AddSingleton ajuda bastante.

Para APIs autenticadas, troque o provedor anônimo. Por exemplo, o BaseBearerTokenAuthenticationProvider recebe um IAccessTokenProvider, que obtém o token em tempo de execução, já que tokens costumam expirar em cerca de uma hora.

Suporte a linguagens e maturidade

Para quem usa o Kiota no .NET, vale saber que a ferramenta classifica o suporte a cada linguagem em níveis de maturidade: stable, preview e experimental. Há ainda o nível abandoned, para linguagens que deixarão de ser mantidas.

O nível stable indica funcionalidade completa e uso em clientes de produção. Nesse caso, quebras de compatibilidade resultam em incremento da versão maior da ferramenta.

O nível preview indica paridade quase completa com stable, mas sem uso produtivo. Já o nível experimental indica suporte parcial, com recursos que podem não funcionar.

O suporte também varia conforme o autor. As linguagens implementadas pela equipe da Microsoft recebem suporte oficial, enquanto as contribuídas pela comunidade contam com a ajuda de outros usuários.

Para consultar o estado atual de cada linguagem, use o comando kiota info.

Bibliotecas companion do Kiota no .NET

O código que o Kiota gera no .NET não é autossuficiente. Ele compila contra interfaces definidas nas bibliotecas companion, que o projeto precisa referenciar.

Existem cinco categorias dessas bibliotecas:

• abstractions: interfaces fundamentais;
• http: implementação do RequestAdapter;
• serialization: JSON, Form, Text e Multipart;
• authentication: provedores de autenticação;
• bundle: metapacote que agrega as demais com um DefaultRequestAdapter.

Para C#, todas ficam consolidadas no repositório microsoft/kiota-dotnet, assim como Java e TypeScript têm repositórios únicos. Por outro lado, linguagens como Go, PHP e Ruby mantêm cada componente em repositórios separados, com o padrão kiota-{tipo}-{linguagem}.

Comandos disponíveis na CLI

A CLI do Kiota no .NET cobre o ciclo completo de trabalho com APIs:

O comando info merece destaque:

kiota info --language CSharp

A saída lista os pacotes NuGet necessários com as versões exatas. Assim, configurar o projeto depois da geração fica bem mais simples.

Na prática, search e download também ajudam a montar filtros. Por exemplo, o tutorial da Microsoft baixa a descrição do GitHub com kiota download apisguru::github.com antes de gerar o cliente.

Validação e geração seletiva

Antes de gerar o código, o Kiota no .NET executa regras de validação sobre a descrição OpenAPI. O objetivo é garantir que o documento traga informações precisas para uma boa experiência no cliente.

Entre as regras, estão DivergentResponseSchema, que detecta schemas diferentes entre códigos de sucesso, e GetWithBody, que aponta requisições GET com body. Também existe InconsistentTypeFormat, para pares de tipo e formato incoerentes.

Você pode desativar regras individualmente com --disable-validation-rules. Isso é útil quando uma descrição de terceiros tem imperfeições que não afetam os endpoints de interesse.

A geração seletiva com --include-path e --exclude-path complementa a validação. Dessa forma, só o código necessário é gerado, a base fica enxuta e o tempo de compilação diminui.

Outra opção útil é --exclude-backward-compatible. Ela omite o código mantido apenas por compatibilidade e reduz o cliente, desde que você aceite possíveis quebras em versões futuras.

Mantendo o cliente atualizado

APIs evoluem, e o cliente precisa acompanhar essas mudanças. Para isso, o Kiota no .NET oferece o comando update, que lê os arquivos kiota-lock.json e regenera os clientes com os mesmos parâmetros da geração anterior.

Como o lock file guarda um hash da descrição, a ferramenta pula a geração quando nada mudou. Dessa forma, rodar o comando com frequência não desperdiça tempo de build.

Também vale lembrar que instalar uma versão nova da ferramenta não altera o código já gerado. Segundo a política de suporte, o cliente só usa a versão nova depois de uma regeneração, então teste antes de publicar em produção.

Em pipelines, a action setup-kiota, ainda em preview, instala a ferramenta e permite atualizar os clientes automaticamente:

steps:
  - uses: actions/checkout@v3

  - uses: microsoft/setup-kiota@v0.5.0

  - name: Update kiota clients in the repository
    run: kiota update -o .
    working-directory: src

Com esse passo no workflow, o repositório recebe clientes sempre alinhados com a descrição mais recente. Assim, divergências entre API e cliente aparecem cedo, ainda na revisão do pull request.

Quando usar o Kiota no .NET

O Kiota faz mais sentido quando a aplicação consome várias APIs descritas em OpenAPI. Nesse cenário, um único padrão de autenticação, serialização e tratamento HTTP simplifica muito a manutenção.

Ele também se destaca em APIs enormes, como o Microsoft Graph, graças à geração seletiva. Afinal, gerar só os caminhos usados evita carregar milhares de classes desnecessárias.

Por outro lado, se a API não tem descrição OpenAPI ou se a descrição está muito incompleta, o ganho diminui. Nesse caso, vale primeiro melhorar o documento, porque a qualidade do cliente depende diretamente da qualidade da descrição.

Se a sua equipe controla a API e o cliente, dá até para automatizar a geração no build. O artigo sobre gerar o cliente Kiota no build do ASP.NET Core mostra esse fluxo com MSBuild.

Considerações finais

O Kiota no .NET muda a forma de consumir APIs, tanto em aplicações .NET quanto em outras plataformas. Ao centralizar a lógica em um CodeDOM agnóstico e aplicar refinamentos por linguagem em um estágio separado, ele garante consistência sem perder flexibilidade.

Para equipes que integram várias APIs REST, o Kiota elimina a fricção de dependências heterogêneas e unifica autenticação e serialização. Além disso, entrega uma experiência fortemente tipada, com navegação pela IDE, que reduz a curva de aprendizado de cada nova API.

FAQ

O Kiota substitui o Swagger Codegen e o NSwag?

As ferramentas atendem casos parecidos com abordagens diferentes. O NSwag usa templates e pode gerar clientes e controllers completos, enquanto o Kiota gera código mínimo e delega a infraestrutura às bibliotecas companion.

Posso usar o Kiota com APIs internas fora de registros públicos?

Sim. O parâmetro --openapi aceita URLs e caminhos locais, então você pode apontar para um arquivo .yaml ou .json no disco.

Como o Kiota lida com OAuth2 e tokens Bearer?

O Kiota fornece a interface IAuthenticationProvider em vez de gerar código de autenticação. A biblioteca Microsoft.Kiota.Authentication.Azure implementa essa interface com o Azure Identity, e o BaseBearerTokenAuthenticationProvider atende outros provedores de token.

O Kiota funciona com descrições Swagger 2.0?

O Kiota lê a descrição com a biblioteca Microsoft.OpenApi.NET, que aceita OpenAPI nas versões 2 e 3. Ainda assim, a documentação e os exemplos focam em OpenAPI 3.

Dá para regenerar o cliente sem perder customizações?

O comando update regenera a partir das gerações anteriores, mas sobrescreve os arquivos do diretório de saída. Por isso, mantenha customizações fora desse diretório ou use herança e métodos de extensão.

O Kiota faz paginação automática?

Não. Para o Microsoft Graph, a biblioteca Microsoft.Graph.Core oferece um PageIterator compatível, mas em APIs genéricas a paginação fica a cargo de quem consome o cliente.