Skip to content

From a file

A file source is an OpenAPI document that lives with the code. It is the simplest source: the build needs no network once the packages are restored, and a change to the API shows up as a diff of the document.

The Include is a path relative to the project. A .json file is read as JSON, and a .yaml or .yml file as YAML:

<ItemGroup>
<OpenApiClient Include="openapi/rockets.yaml" Generator="Refitter" ClientName="RocketsClient" Namespace="MyApp.Rockets" />
</ItemGroup>

Anything that is not a project (.csproj, .fsproj, .vbproj) or a URL (http://, https://) is a file. A file that does not exist fails the build with CHIRO102.

The project writes no code for the client. Its registration, AddRocketsClient(), reads the client’s options from Clients:RocketsClient or a connection string, takes a configure argument for code, and returns the IHttpClientBuilder for handlers of your own:

builder.Services
.AddRocketsClient(options => options.Timeout = TimeSpan.FromSeconds(30))
.AddStandardResilienceHandler();

Register the authentication keyed with the client’s name, then the client:

// Kiota
builder.Services.AddKeyedSingleton<IAuthenticationProvider>(
"RocketsClient",
(services, _) => new BaseBearerTokenAuthenticationProvider(services.GetRequiredService<IAccessTokenProvider>()));
// Refitter
builder.Services.AddKeyedSingleton(
"RocketsClient",
(services, _) => new RefitSettings
{
AuthorizationHeaderValueGetter = (request, cancellationToken) =>
services.GetRequiredService<ITokenSource>().GetTokenAsync(cancellationToken),
});
builder.Services.AddRocketsClient();

See Authentication for the lookup, and the options’ delegates that have the last word.

Give each client its own ClientName, and its own Namespace when they share a project, so their generated types don’t collide:

<ItemGroup>
<OpenApiClient Include="openapi/rockets.json" Generator="Kiota" ClientName="RocketsClient" Namespace="MyApp.Rockets" />
<OpenApiClient Include="openapi/launches.json" Generator="Refitter" ClientName="LaunchesClient" Namespace="MyApp.Launches" />
</ItemGroup>

Two clients can share a document, for example to compare the generators. Each one gets its own copy of the document in its own folder in obj.

Replace the file and build. Chirograph copies the document into obj only when its content changed, and the generator only runs again when that copy, or the client’s settings, changed. Saving the file with the same content regenerates nothing. See How generation runs.

Options is added to the generator’s command line: after kiota generate … for Kiota, and after the settings file for Refitter.

<OpenApiClient
Include="openapi/rockets.json"
Generator="Kiota"
ClientName="RocketsClient"
Options="--include-path /rockets/**"
/>

A change to Options generates the client again. Options that change where the output goes or what the client is called fight with the ones Chirograph passes; see Generators for what those are.