Kiota.Tools 0.1.0

Kiota.Tools

Generate strongly-typed REST API clients from OpenAPI specs automatically at build time — no manual codegen step, no checked-in generated code.

Inspired by Grpc.Tools: reference the package, point at your spec, build.

Quick start

<ItemGroup>
    <PackageReference Include="Kiota.Tools" Version="1.0.0" />
</ItemGroup>

<ItemGroup>
    <KiotaOpenApiSpec Include="openapi.yaml">
        <Namespace>MyApp.ApiClient</Namespace>
        <ClientClassName>MyApiClient</ClientClassName>
    </KiotaOpenApiSpec>
</ItemGroup>

dotnet build    # client generated into obj/generated/*

var adapter = new HttpClientRequestAdapter(new AnonymousAuthenticationProvider());
var client  = new MyApiClient(adapter);

var pets = await client.Pets.GetAsync();

That should™ be it.

How it works

dotnet build
    │
    ├─ BeforeTargets="CoreCompile"
    │       KiotaRunGenerate
    │           └─ kiota generate --language CSharp
    │                   --openapi openapi.yaml
    │                   --output  obj/generated/openapi/
    │                   --namespace-name MyApp.ApiClient
    │                   --class-name MyApiClient
    │
    ├─ AfterTargets="KiotaRunGenerate"
    │       KiotaAddGeneratedFilesToCompile
    │           └─ <Compile Include="obj/generated/**/*.cs" />
    │
    └─ CoreCompile  ← generated files already in Compile item group

Generation uses stamp files (obj/generated/<specname>.stamp) for incremental builds — kiota only runs when the spec changes.

Reference

Item metadata

Properties

Multiple specs

<ItemGroup>
  <KiotaOpenApiSpec Include="weather-api.yaml">
    <Namespace>MyApp.Weather</Namespace>
    <ClientClassName>WeatherClient</ClientClassName>
  </KiotaOpenApiSpec>

  <KiotaOpenApiSpec Include="payments-api.yaml">
    <Namespace>MyApp.Payments</Namespace>
    <ClientClassName>PaymentsClient</ClientClassName>
  </KiotaOpenApiSpec>
</ItemGroup>

Each spec gets its own sub-folder and stamp file under obj/generated/, so incremental builds track them independently.

kiota tool resolution

The package locates kiota in this order:

1. $(KiotaToolPath) — explicit path wins
2. Local .NET tool — dotnet tool run kiota (reads .config/dotnet-tools.json)
3. Global .NET tool — kiota on PATH
4. Auto-install — runs dotnet tool install -g Microsoft.OpenApi.Kiota with a warning

For CI, a local tool manifest is recommended so the version is pinned:

dotnet new tool-manifest
dotnet tool install Microsoft.OpenApi.Kiota
git commit .config/

CI then just needs dotnet tool restore before the first build.

Generated file layout

obj/
└── generated/                        ← KiotaOutputPath (covered by .gitignore via obj/)
    └── openapi/                      ← OutputSubPath (spec filename, no extension)
        ├── ApiClient.cs              ← top-level client (ClientClassName)
        ├── Models/
        │   ├── Pet.cs
        │   └── Error.cs
        └── Pets/
            ├── PetsRequestBuilder.cs
            └── Item/
                └── PetsItemRequestBuilder.cs